# Meta Ads: how to read it into Maplith

*Ads · also known as Meta Ads Manager, Facebook Ads, Instagram Ads · last checked 2026-10-08 · recipe `maplith://systems/meta-ads`*

Meta Ads holds the campaigns, ad sets and ads a company runs on Facebook and Instagram and what each one spent and delivered per day, which links marketing spend to orders and revenue.

## 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 (ADR-0031):

1. **Your agent fetches it**, with the access your human already gave you. No named client connector confirmed: check the tools you already have. The customer's 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.
2. **Maplith reads an MCP server your human already has.** Official: **Meta ads MCP server**. Endpoint to connect to: `https://mcp.facebook.com/ads`. Documentation (a page to read, not an address to connect to): https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-mcp-server/ads-mcp-server-overview. Access: There is no read-only token: the client signs in with Facebook Login for Business, or uses a user access token that Meta says needs ads_read plus 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: it offers tools or a personal sign-in to an agent, not resources Maplith reads. Maplith reads only a server that serves MCP resources and takes a token a person types under Data sources › Systems in the Maplith app, such as the customer-run template for a database (ADR-0028). Your human can connect this server to you instead, as path 1.
3. **Export files**, the fallback that always works: see *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: your human decides what goes in.

## Read-only access

**Who usually has the rights:** The business portfolio admin, often the owner or marketing lead, or the agency that runs the ads.

**For the key your own agent's client uses, choose only these read permissions:** `ads_read`, `Reporting only (ANALYZE) access on the ad account`

**Where to click:**

1. Open Meta Business Suite and go to Settings for the business portfolio
2. Click People in the left menu
3. Add or pick the person, choose employee access, then click Next
4. Select the ad account and turn on only the reporting task under standard access
5. Click Invite and wait for the person to accept

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, and only for an MCP server it can read.

## Export steps

**Format:** CSV or XLSX · **Date range:** The last three to six months

1. Open Ads Manager and go to Ads Reporting
2. Build a report at ad level with campaign, ad set and ad ids and names, broken down by day
3. Add the columns amount spent, impressions, clicks, results and purchases
4. Set the date range to the last few months
5. Click Export, choose CSV or XLSX (raw data), and click Export

## Volume hint

**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.

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.

## 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-08:

- https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-mcp-server/ads-mcp-server-overview
- https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-mcp-server/ads-mcp-server-get-started
- https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-mcp-server/ads-mcp-server-tools-comprehensive-reporting
- https://www.facebook.com/business/news/meta-ads-ai-connectors
- https://developers.facebook.com/documentation/ads-commerce/marketing-api/insights
- https://developers.facebook.com/docs/permissions/reference/ads_read