# Metricool: how to read it into Maplith

*Social media planning and analytics · also known as Metricool social media, Metricool planner · last checked 2026-10-27 · recipe `maplith://systems/metricool`*

Brands, connected social channels, scheduled posts and metric totals by period: how the social media team plans and reports.

## Best path

**Recommended: your agent fetches it.** Metricool's hosted MCP server lets an agent that has signed in read the brands, the scheduled posts and the metric totals by period. Maplith's own integration reads the same server on the workspace's scan schedule, once it is open to the workspace. Metricool's separate API-key server is a different connection.

Try the paths in this order (ADR-0031):

1. **Your agent fetches it**, with the access your human already gave you. Connectors a vendor or client page confirms: Metricool MCP in ChatGPT (by its URL); Metricool MCP in Claude Code (by its URL). The agent connects Metricool's hosted MCP server by its URL, signs in to Metricool, and reads the brand settings, the posts scheduled ahead and, for each connected network, the metrics it offers and their totals for a past period. It never calls the tools that create, change or send posts for review.
2. **Maplith reads an MCP server your human already has.** Official: **Metricool MCP**. Endpoint to connect to: `https://ai.metricool.com/mcp`. Documentation (a page to read, not an address to connect to): https://help.metricool.com/en/article/how-to-connect-metricools-mcp-1364s63/. Access: The hosted server uses OAuth: approve read access in the browser. Metricool's separate API-key server is a different connection. The hosted server offers read tools and tools that change posts. Maplith's integration calls only the read tools for brands, scheduled posts, the metrics a network offers and their totals, and not the best-time-to-post suggestions, which describe no part of the business. Maplith reads this server through its own integration, described in *Maplith's integration* below; it is not a server your human adds under Data sources › Systems.
3. **Export files**, the fallback that always works: see *Export steps* below.
4. **Maplith's own integration** (built, and not open to every workspace yet: it opens once it is released; until then, share the export): see *Maplith's integration* below.

## Datasets that make a good map

| Dataset | One row is | Key columns | Joins to |
|---|---|---|---|
| Brands and channels | One brand and its connected networks, including its time zone. | brand id, brand label, network, time zone | Scheduled posts, metric catalogue and analytics by brand id and network. |
| Scheduled posts | One post planned for a future date on one or more networks. | scheduled post id, brand id, publication date, draft or approval state | Brands by brand id. |
| Metric catalogue | One metric id found for a network, with its label and aggregation rule. | metric id, network, connector, metric label, aggregation rule | Analytics by metric id and network. |
| Analytics | One aggregate value per metric, brand, network and requested period; no individual published posts. | brand id, network, metric, period start, period end, value | Brands and channels by brand id and network; metric catalogue by metric id and network. |

Columns are named, never their values. Maplith tries to mask personal data such as email addresses, but that is best effort: your human decides what goes in.

## Read-only access

**Who usually has the rights:** The Metricool account owner, or a team member with access to the brands to be read.

**For the key your own agent's client uses, choose only these read permissions:** `Sign in to Metricool when the client connects its MCP server, and approve its access`, `Access to each brand the map should cover`

**Where to click:**

1. In the AI client, add a connector or MCP server with the address https://ai.metricool.com/mcp
2. Sign in to Metricool in the browser window that opens
3. Approve the access, then ask the agent to list the brands

A key or token made here stays in the tool that reads the system for your human, never in a chat. Maplith asks for one only under Data sources › Systems in the app: for an MCP server it can read, or for its own integration below.

## Export steps

**Format:** CSV · **Date range:** The last three months

1. Metricool's help describes no CSV of a network's metric totals; your agent or Maplith's integration reads them.
2. Scheduled posts: export the posts of the Calendar or an Autolist to CSV from the Planner.
3. Brands and channels need no file of their own: the scheduled-posts file names its brand and network.
4. Repeat for each network and brand the map should cover, and upload the files in Data sources › Scans.

## Volume hint

**About 10–100 scheduled posts and a few hundred metric totals per brand a month** (an estimate). Estimate for a small team planning about a post a day on a few networks and tracking a few metrics per network, not a measured figure.

Every row an agent reads passes through its context, about one token per four characters. Above a few thousand rows a dataset, or for a daily refresh, prefer an MCP server or an export over fetching through the chat.

## Maplith's integration

**Status:** built, and not open to every workspace yet: it opens once it is released; until then, share the export.

**How to connect:**

1. In Maplith, open Data sources › Systems and choose Connect Metricool. You need to be an admin or builder of the workspace.
2. Metricool asks you to sign in and approve read access for Maplith: approve it there. Maplith asks for Metricool's read scope only.
3. Metricool returns you to Data sources › Systems. Maplith checks that it is you, in the workspace you started from, before it stores anything; the access is sealed and never shown again.
4. Scan it from the connection, or wait for the workspace's scan schedule.

**The permissions it needs, and why:**

- `mcp:read`: Reads brands, scheduled posts, the metric catalogue and metric totals by period; mcp:write is never requested.

**What it reads:**

- Brand settings and connected networks, posts scheduled for the next 90 days, the metrics each network offers and their totals by period over the last 90 days, through the hosted server's read tools
- Tables of brands, channels, scheduled posts, metrics and their totals, read during the scan and deleted when it ends; Maplith tries to mask personal data as in uploaded exports
- What Maplith keeps is the map, and the totals of any metric you choose to track; individual published posts and campaigns are not kept

**What it never reads or does:**

- Anything that changes Metricool: the server's tools that schedule or update a post are never called
- Inbox messages, comments, reviews, SmartLinks, competitor profiles or connected Canva and Drive files
- Metricool's write scope: it is never asked for
- Your Metricool access anywhere but sealed in Maplith: it is never shown again and never sent to a model

**Choosing what is read:** Maplith reads every brand the account can see, up to 25, over the last 90 days and the next 90; there is no filter to set. To read less, share Metricool's CSV exports instead of connecting.

## What Maplith sets up once it is connected

Maplith builds these itself; a person corrects them, and never has to approve them first (ADR-0038). If the system is disconnected, Maplith takes the playbooks it set up and nobody changed out of use, and puts them back when the system is connected again; a playbook a person changed stays as they left it.

**Signals:**

| Kind | Delivery | When |
|---|---|---|
| `link_dead` | poll | a regular check finds the access revoked or lapsed, the server unreachable, or a read tool Maplith needs changed or gone |
| `structure_changed` | poll | the connection offers at least a quarter more or fewer resources than at the last check |
| `finding_added` | poll | a scan finds a flaw in how posts are planned or reported, such as a channel nobody posts to |

**Checks:**

- **Connection probe** (every 12 hours): checks that Metricool still grants the access and offers its read tools, and calls none of them
- **Read allow-list** (on every call): refuses any Metricool tool that is not one of its read tools before a request is sent

**Suggested playbooks:**

- **Reconnect Metricool.** Starts when the Metricool connection's link_dead signal is raised. Steps: Open Data sources › Systems and run Test connection to read the reason; If Metricool no longer grants the access, remove the connection and choose Connect Metricool again; If Metricool could not be reached, wait a few minutes and test again; Run Test connection again and record what was done.
- **Review a change in the social channels.** Starts when a scan finds a channel or a field of Metricool's data added or gone. Steps: Read the signal: it names the object and the field that changed, never a post; Ask the social media team whether the change was planned, such as a network connected or removed in Metricool; Record the answer on the signal.

**Schedules:**

- **Read Metricool** (with the workspace's scan schedule (daily or weekly)): the map of brands, connected channels, schedules and metric totals by period stays current

**What setup integrity expects:**

- The Metricool connection exists and its last probe succeeded
- The metricool source has an owner and a refresh cadence (Maplith states them from the workspace owner and the scan schedule; a person corrects them)
- Each suggested playbook exists, or a person removed it, and is anchored on a signal kind the connection raises

## How the connection works

Every Maplith integration provides the same things. For Metricool:

**Install.** Or open Data sources › Systems and choose "Connect Metricool". You give access once, in Metricool's own consent screen, and never type or paste a token. Before anything is stored Maplith checks:

- The request started in your workspace in the last 15 minutes and was not changed on the way
- You are the same person who started it, still signed in, and still an admin or builder of that workspace
- Connecting Metricool is open in that workspace and it has no Metricool connection yet
- Metricool's server answers and offers the read tools, before the access is stored

**Read.** Maplith reads Metricool through the read-only tools of its MCP server at `https://ai.metricool.com/mcp`, from a fixed list: `getBrandSettings`, `getScheduledPosts`, `getAnalyticsAvailableMetrics`, `getAnalyticsDataByMetrics`. A call to anything else is refused before it is sent. It never calls `createScheduledPost`, `updateScheduledPost`, `createScheduledPostForReview`, `sendScheduledPostForReview`, which change something. Tables of brands, channels, scheduled posts, metrics and one total per metric, brand, network and period, read during the scan and deleted when it ends; Maplith tries to mask personal data in them. Published posts and individual ad campaigns are not read.

**Scan.** The connection is scanned on the workspace's scan schedule, daily or weekly. The first scan is one you ask for from the connection; after that it follows the schedule. Every 12 hours the connection is checked without reading any content: Metricool must still grant the access (renewed when it is about to expire) and offer its read tools. If it does not, Maplith raises link_dead with the steps that repair it, and clears it when the connection recovers.

**Events.** Metricool sends no events Maplith can receive: Metricool sends no webhooks to an app, so there is nothing to receive. The workspace's scan schedule and the 12-hour probe carry the connection.

**Remove it.** Remove under Data sources › Systems deletes Maplith's sealed copy of the access and the connection. Metricool offers no endpoint for Maplith to revoke its access itself, so the page says so. To end the access in Metricool too, revoke Maplith's access in your Metricool account. The map built from Metricool stays, marked as no longer maintained. Signals stay for their retention. The playbooks Maplith set up for it are taken out of use, not deleted.

**Your own agent.** Maplith never writes in Metricool. Your agent does, with its own access, once Maplith's action gate allows it. This connector reads Metricool only. Scheduling a post through your own agent and Maplith's action gate is a later step, once Maplith has learned how your team works.

Maplith wakes a subscribed agent (ADR-0036) when this connection raises `link_dead`.

## Always

- Read-only, and never a credential sent to Maplith through the chat.
- The same recent period, a few months, from every system.
- Your human decides what goes in.

## Sources

Written from the vendor's public documentation, last checked 2026-10-27:

- https://help.metricool.com/en/article/how-to-connect-metricools-mcp-1364s63/
- https://help.metricool.com/mcp-limits-and-plan-requirements-h72jg
- https://metricool.com/metricool-mcp/
- https://ai.metricool.com/.well-known/oauth-protected-resource
- https://ai.metricool.com/.well-known/oauth-authorization-server
- https://help.metricool.com/how-to-use-and-explore-the-analytics-tab-lmd52
- https://help.metricool.com/how-to-sync-and-understand-your-campaign-dashboard-8jst3
- https://metricool.com/import-csv-for-scheduling/