Meta Ads MCP

An MCP server for the Meta Marketing API — built for people running real ad spend.

118 typed tools across Ads, Insights, Pixels/CAPI, Pages, Instagram, WhatsApp Business, Catalogs, Audiences, Leads and Billing — with the token kept out of your config files and a confirmation gate on every destructive call.

Why this one

There are several Meta Ads MCP servers out there. This one is built around a specific assumption: the person using it is spending real money, possibly on behalf of clients, and a mis-fired tool call costs more than an apology.

That shapes three decisions the code makes differently:

Plus a global MCP_READ_ONLY kill switch — useful when the server is reachable from a phone.

Related MCP server: ads-mcp

Quick start

Requirements: Python 3.11+, a Meta System User token, and an MCP client (Claude Code, Claude Desktop, Cursor…).

git clone https://github.com/AbnerZx/meta-ads-mcp.git
cd meta-ads-mcp
powershell -ExecutionPolicy Bypass -File .\install.ps1

The installer checks your Python, creates .venv, installs dependencies, prompts for your token (masked input, stored in Credential Manager, never written to disk), and prints the exact registration command to run next.

git clone https://github.com/AbnerZx/meta-ads-mcp.git
cd meta-ads-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
python -m keyring set meta-ads-mcp access_token   # paste token when prompted

Then register it with your client:

claude mcp add meta-ads --scope user -- /path/to/.venv/bin/python /path/to/src/server.py

Restart the client. Tools appear as mcp__meta-ads__*.

Verify it works — ask your assistant:

"List my Meta ad accounts."

What's in it

118 tools across 12 modules:

graph_call matters more than it looks. The Meta Marketing API is enormous and changes often. Rather than pretend 118 tools cover it, there's a typed escape hatch for any endpoint that isn't wrapped yet — so you're never blocked waiting on this repo.

Conventions

Worth knowing before your first call:

• Ad account IDs are auto-prefixed with act_ — pass 123456 or act_123456, both work.

• Budgets are integers in account-currency cents. R$ 10,00 → 1000. This is Meta's convention, not ours.

• Destructive ops need confirm=True. Without it you get a blocked-operation error naming the target.

• The token never travels through tool arguments. It's loaded once at startup from the credential store.

Security model

The threats this is designed against, and what handles each:

Found a vulnerability? See SECURITY.md — please don't open a public issue.

Getting a token

Use a System User token, not a personal one. It doesn't expire, it's revocable independently of your own account, and Meta gives you a per-user audit trail.

Business Manager → Business settings → Users → System users → Add → assign only the ad accounts and Pages you actually need → Generate new token.

Typical scopes: ads_management, ads_read, business_management, read_insights. Add pages_*, instagram_*, leads_retrieval, whatsapp_business_* or catalog_management only if you use those modules. Meta shows the token exactly once.

Configuration

All optional except the token. See .env.example.

Remote deployment

The server speaks two transports: stdio for local clients, streamable-http for remote ones. The HTTP mode lets you reach your ad accounts from Claude.ai on mobile via a Custom Connector.

→ Full deployment guide (DEPLOY.md) — Fly.io walkthrough, bearer secret generation, secret rotation, and an incident-response checklist.

Short version:

fly launch --no-deploy --copy-config    # edit fly.toml first: app name + MCP_PUBLIC_HOSTS
fly secrets set MCP_BEARER_SECRET="..." META_ADS_TOKEN="..."
fly deploy

fly.toml ships with MCP_READ_ONLY = 'true'. Leave it that way until you've confirmed the deployment works.

Project layout

src/
├── server.py           # stdio entrypoint
├── http_server.py      # streamable-http transport, bearer auth, rate limiting
├── mcp_instance.py     # shared FastMCP instance + transport security
├── client.py           # Graph API client — retries, backoff, log scrubbing
├── auth.py             # token loading (credential store → env fallback)
├── safety.py           # confirmation gate, ID normalization, input validation
└── tools/              # 12 modules, 118 tools

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md. Especially useful: Graph API error subcodes you've hit that aren't decoded yet, and coverage gaps you're currently working around with graph_call.

License

MIT © Abner Ferreira

Not affiliated with or endorsed by Meta Platforms, Inc. "Meta", "Facebook", "Instagram" and "WhatsApp" are trademarks of Meta Platforms, Inc.