Docs: System guides
Read Meta Ads into Maplith
On this page
Best path
Recommended: export files. A small company's daily ad report is a few hundred rows a month, and a report export from Ads Manager is read-only by nature. Meta's official ads MCP server works too, but it was announced as an open beta and its token needs ad-management permissions, so it is not a clean read-only path.
Try the paths in this order:
- Your agent fetches it, with the access you already gave it. No named connector is confirmed: check the tools your agent already has. Your agent checks the tools it already has; if Meta's ads MCP server is connected, it reads the campaign, ad set and ad list and a daily performance report for a few recent months, without changing anything.
- Maplith reads an MCP server you already run. Meta Ads runs Meta ads MCP server. Its address is
https://mcp.facebook.com/ads. Documentation: developers.facebook.com. There is no read-only token: the client signs in with Facebook Login for Business, or uses a user access token that Meta says needsads_readplus ad- and catalog-management permissions. Give the signed-in person only reporting access on the ad account, and let a business portfolio owner set server rules that limit what agents can change. The server is hosted by Meta and also has tools that create and edit ads, campaigns and catalogs. Maplith cannot read this server itself, because it offers tools or a personal sign-in to an agent. Connect it to your agent instead, as the first path. - Export files, the fallback that always works. See the export steps below.
Datasets that make a good map
| Dataset | One row is | Key columns | Joins to |
|---|---|---|---|
| Campaigns | One row per campaign. | campaign id, campaign name, objective, status, start date | Shop orders and web analytics by the campaign name or UTM campaign tag, when the ads carry UTM tags. |
| Ad sets | One row per ad set inside a campaign, with its budget and schedule. | ad set id, campaign id, ad set name, budget, status | Campaigns by campaign id; ads and daily performance by ad set id. |
| Ads | One row per ad, with its link and URL parameters. | ad id, ad set id, campaign id, ad name, destination URL, URL parameters (UTM tags) | Shop orders and web analytics sessions by UTM source, medium, campaign and content; ad sets by ad set id. |
| Daily performance | One row per ad (or campaign) per day: spend and delivery. | date, campaign id, ad set id, ad id, spend, currency, impressions, clicks, results, purchases | Shop orders by date and UTM campaign; Meta charges in the accounting system by month and total spend. |
| Activity history | One row per change made in the ad account (budget, status, edits). | date and time, changed campaign, ad set or ad, type of change | Campaigns, ad sets and ads by their ids; explains jumps in daily spend. |
Columns are named, never their values. Maplith tries to mask personal data such as email addresses, but that is best effort: you decide what goes in.
The access to give
Who usually has the rights: The business portfolio admin, often the owner or marketing lead, or the agency that runs the ads.
Choose the narrowest access that covers the data:
ads_read- Reporting only (ANALYZE) access on the ad account
Where to click:
- Open Meta Business Suite and go to Settings for the business portfolio
- Click People in the left menu
- Add or pick the person, choose employee access, then click Next
- Select the ad account and turn on only the reporting task under standard access
- Click Invite and wait for the person to accept
A key or token made here stays in the tool that reads the system, never in a chat. Maplith asks for one only under Data sources › Systems in the app.
Export steps
Format: CSV or XLSX Date range: The last three to six months
- Open Ads Manager and go to Ads Reporting
- Build a report at ad level with campaign, ad set and ad ids and names, broken down by day
- Add the columns amount spent, impressions, clicks, results and purchases
- Set the date range to the last few months
- Click Export, choose CSV or XLSX (raw data), and click Export
How much data
About 150–1,500 ad-day rows a month (an estimate). Estimate for a small company, not a measured figure: roughly 5–50 active ads, one row each per day.
An agent that reads rows through a chat reads every one of them, about one token per four characters. Above a few thousand rows a dataset, or for a daily refresh, an MCP server or an export is the better path.
Always
- Read-only, and never a credential sent to Maplith through a chat.
- The same recent period, a few months, from every system.
- You decide what goes in.
Sources
Written from public documentation, last checked 2026-10-08: