flin-meta-ads-mcp

flin-meta-ads-mcp is a public, strict read-only MCP server for Meta Ads. It is designed to be installed with uvx and loaded into Claude with minimal setup.

What it does

• Lists and reads Meta Ads accounts
• Reads campaigns, ad sets, ads, ad images, and creatives
• Gets ad previews (including preview_url links)
• Fetches insights for account, campaign, ad set, and ad levels
• Stays read-only in v0.1.x

Scope for v0.1.x

This release is strictly read-only.

That means:

• No create, update, pause, resume, or delete actions
• No OAuth flow or token refresh
• No generic Graph API proxy

Install

Install and run the latest published PyPI release:

uvx flin-meta-ads-mcp

Install and refresh to the newest published release:

uvx --refresh flin-meta-ads-mcp

Run the latest GitHub code (main branch):

uvx --refresh --from git+https://github.com/flin-agency/flin-meta-ads-mcp.git flin-meta-ads-mcp

Claude config

Stable (latest published PyPI release, refreshed):

{
  "mcpServers": {
    "flin-meta-ads-mcp": {
      "command": "uvx",
      "args": ["--refresh", "flin-meta-ads-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "EAA...",
        "META_GRAPH_API_VERSION": "v21.0"
      }
    }
  }
}

Latest GitHub code (main branch, refreshed):

{
  "mcpServers": {
    "flin-meta-ads-mcp": {
      "command": "uvx",
      "args": [
        "--refresh",
        "--from",
        "git+https://github.com/flin-agency/flin-meta-ads-mcp.git",
        "flin-meta-ads-mcp"
      ],
      "env": {
        "META_ACCESS_TOKEN": "EAA...",
        "META_GRAPH_API_VERSION": "v21.0"
      }
    }
  }
}

Environment variables

Required:

• META_ACCESS_TOKEN: Meta access token with read permissions

Optional:

• META_GRAPH_API_VERSION: Graph API version, default v21.0
• META_TIMEOUT_SECONDS: request timeout, default 30
• META_MAX_RETRIES: retry count for transient failures, default 3
• META_DEFAULT_AD_ACCOUNT_ID: optional fallback ad account (e.g. act_123...) used when a tool call omits ad_account_id
• RUN_LIVE_META_TESTS: set to 1 to enable live integration tests

Ad account selection:

• If the token has exactly one accessible ad account, the server resolves it automatically.
• If META_DEFAULT_AD_ACCOUNT_ID is set, the server uses it when ad_account_id is omitted.
• If the token has multiple accessible ad accounts, pass ad_account_id in the tool call.

2-minute smoke test

Use these first three tool calls to confirm the server is working:

1. list_ad_accounts
2. list_campaigns
3. get_insights with level=campaign and date_preset=last_7d

Example flow in Claude:

Call list_ad_accounts
Call list_campaigns
Call get_insights with level=campaign and date_preset=last_7d

If the first call works but later calls fail, the issue is usually permissions or ad account scope.

If list_campaigns returns a selection request, call it again with one of the suggested ad_account_id values.

Troubleshooting

Problem	Likely cause	Fix
Token missing	META_ACCESS_TOKEN is not set	Add the env var and restart Claude
Token invalid	Expired or wrong token	Generate a valid Meta read token
Permission denied	Missing ads_read or account access	Grant the token access to the ad account
Ambiguous ad account	Token can access multiple ad accounts	Pass ad_account_id per tool call
Rate limit errors	Meta API throttling	Retry later or reduce the number of insight calls

Development

Local development quickstart:

python -m pip install -e ".[dev]"
pytest -q
ruff check .
mypy src

If you want to run live Meta API tests:

RUN_LIVE_META_TESTS=1 pytest -q

Release

Create and push a release tag:

git tag v0.1.9
git push origin v0.1.9

After release, users can run:

uvx flin-meta-ads-mcp

Notes

• Use only ad accounts you are allowed to access
• This server is intended for analysis and reporting, not mutation
• Public users should treat META_ACCESS_TOKEN as a secret and supply it through environment variables only