# 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

```bash
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

```bash
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](https://adsmanager.facebook.com) URL or account dropdown. Prefix with `act_`.
- **Access Token**: Generate at [Meta Graph API Explorer](https://developers.facebook.com/tools/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`):

```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