meta-ads-mcp-server

Meta Ads MCP Server

MCP Server for the Meta Marketing API. Gives Claude Desktop direct access to your ad account data — campaign performance, creative analysis, audience breakdowns, and budget pacing.

Tools

| Tool | Description | |---|---| | get_campaigns | List campaigns with status, objective, and budget info | | get_campaign_performance | Core KPIs: spend, impressions, CTR, CPC, CPM, CPA, ROAS | | get_creative_performance | Creative-level metrics including video hook rate and thruplay rate | | get_ad_creatives | Inline-render ad creative images (full-resolution by default, image_size: "thumbnail" for 64×64 previews) | | get_audience_breakdown | Performance broken down by age and/or gender | | get_budget_status | Budget pacing and daily spend status for active campaigns | | get_ad_accounts | List all ad accounts the token has access to | | get_adsets / get_ads | List ad sets / ads with optional filtering | | debug_* | Diagnostic helpers for troubleshooting field/breakdown issues |

Setup

1. Install & Build

git clone https://github.com/YOUR_USERNAME/meta-ads-mcp-server.git
cd meta-ads-mcp-server
npm install
npm run build

2. Configure Environment

cp .env.example .env

Edit .env with your credentials:

META_ACCESS_TOKEN=your_meta_api_token
META_AD_ACCOUNT_ID=act_123456789

Getting your credentials:

• Ad Account ID: Found in Meta Ads Manager URL or account dropdown. Prefix with act_.
• Access Token: Generate at Meta Graph API Explorer with ads_read permission. Short-lived tokens (~2h) can be exchanged for 60-day long-lived tokens via GET /oauth/access_token?grant_type=fb_exchange_token&client_id={APP_ID}&client_secret={APP_SECRET}&fb_exchange_token={SHORT_TOKEN}.

The .env file takes precedence over environment variables passed by Claude Desktop. If Claude Desktop's claude_desktop_config.json contains a stale META_ACCESS_TOKEN, the value in .env wins. Update .env to rotate the token without touching Claude Desktop config.

3. Add to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "meta-ads": {
      "command": "node",
      "args": ["/absolute/path/to/meta-ads-mcp-server/dist/index.js"]
    }
  }
}

On macOS with Homebrew Node, use /opt/homebrew/bin/node as the command.

Restart Claude Desktop. The tools will be available automatically.

Usage Examples

Ask Claude things like:

• "Show me my active campaigns"
• "How did campaign 120210001 perform last 7 days?"
• "Compare creative performance for my Summer Sale campaign"
• "Break down my campaign audience by age and gender"
• "Are any campaigns overspending today?"

Architecture

src/
├── index.ts             → MCP server setup, tool registration
├── types.ts             → Shared interfaces (MetaInsight, MetaAction, etc.)
├── fields.ts            → Reusable Meta API field selections
├── formatters.ts        → KPI calculations, number formatting
├── meta-client.ts       → Meta API client (loads .env with override:true)
└── tools/
    ├── campaigns.ts     → get_campaigns
    ├── performance.ts   → get_campaign_performance
    ├── creatives.ts     → get_creative_performance
    ├── ad-creatives.ts  → get_ad_creatives (inline image rendering)
    ├── audience.ts      → get_audience_breakdown
    ├── budget.ts        → get_budget_status
    ├── accounts.ts      → get_ad_accounts
    ├── adsets.ts        → get_adsets
    ├── ads.ts           → get_ads
    └── debug.ts         → debug helpers

Meta API Notes

• Budgets are in cents. daily_budget: "5000" = €50.00
• Actions are arrays. Always parsed with extractAction(), never accessed directly
• Breakdowns multiply rows. age,gender gives ~14 rows per campaign (7 age groups × 2 genders)
• Video fields may be missing. Non-video ads won't have video_thruplay_watched_actions
• date_preset vs time_range: Never send both — Meta throws an error

License

MIT