Media Buyer Plugin

MCP plugin for managing Meta Ads (Facebook/Instagram) and Google Ads from Claude Desktop and Claude Code.

79 tools: 45 Meta Ads + 34 Google Ads — campaign management, creative upload, audience targeting, reporting, and smart automation.

Quick Start — Claude Desktop

Meta Ads

1. Install Node.js 20+ (LTS)
2. Open Claude Desktop → Settings (gear icon) → Developer → Edit Config
3. Add this to your config:

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "media-buyer-plugin", "--meta"],
      "env": {
        "META_ADS_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

4. Replace YOUR_TOKEN_HERE with your Meta System User Token
5. Save and restart Claude Desktop

Google Ads

Add this alongside the meta-ads entry:

{
  "mcpServers": {
    "meta-ads": { "..." : "..." },
    "google-ads": {
      "command": "npx",
      "args": ["-y", "media-buyer-plugin", "--google"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEV_TOKEN",
        "GOOGLE_ADS_CLIENT_ID": "YOUR_CLIENT_ID",
        "GOOGLE_ADS_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MCC_ID"
      }
    }
  }
}

Both platforms

You can run Meta Ads and Google Ads simultaneously — they are independent MCP servers.

Quick Start — Claude Code

# Install
npm install -g media-buyer-plugin

# Meta Ads
claude mcp add -s user meta-ads -- media-buyer-meta

# Google Ads
claude mcp add -s user google-ads -- media-buyer-google

Or use the interactive setup:

git clone https://github.com/kv-consulting/media-buyer-plugin.git
cd media-buyer-plugin
npm install && npm run build
bash config/setup.sh

Usage

Talk naturally to Claude:

"list my ad accounts"
"create a campaign for Terramundi with R$100/day budget"
"pause ad 123456789"
"show me last 7 days performance for all campaigns"
"what keywords are wasting budget?"
"duplicate adset 987654321"

Meta Ads Tools (45)

Write (13 tools)

| Tool | Description | |------|-------------| | meta_ads_create_campaign | Create campaign (CBO or ABO). Budget in BRL. Always PAUSED. | | meta_ads_create_adset | Create ad set with targeting, budget and optimization. | | meta_ads_upload_image | Upload image (local file or URL). Returns hash for creatives. | | meta_ads_upload_video | Upload video (local or URL). Waits for processing. | | meta_ads_create_lead_form | Create lead gen form on a Page. Immutable after creation. | | meta_ads_create_creative | Create creative: simple, flexible, carousel, video, or DPA. | | meta_ads_create_ad | Create ad linking adset + creative. Always PAUSED. | | meta_ads_update_campaign | Edit campaign name, budget, bid strategy. | | meta_ads_update_adset | Edit ad set targeting, budget, dates, optimization. | | meta_ads_update_ad | Edit ad name or swap creative. | | meta_ads_update_status | Pause, enable or archive (batch). | | meta_ads_duplicate_adset | Duplicate ad set for A/B testing. | | meta_ads_validate_token | Validate configured access token. |

Read (19 tools)

| Tool | Description | |------|-------------| | meta_ads_list | List campaigns, ad sets or ads. Filter by status. | | meta_ads_search | Search by name. | | meta_ads_get_ad_preview | Visual ad preview (HTML). | | meta_ads_get_delivery_insights | Review status, delivery, learning phase. | | meta_ads_get_insights | Performance metrics (impressions, spend, CPC, CPM, CTR, conversions). | | meta_ads_list_accounts | List all ad accounts from Business Manager. | | meta_ads_list_creatives | List creative library (flexible, video, carousel). | | meta_ads_list_images | List uploaded images (with hash for reuse). | | meta_ads_list_videos | List videos with processing status. | | meta_ads_get_video_status | Check video processing status. | | meta_ads_list_placements | List available placements (Facebook, Instagram, AN). | | meta_ads_get_pixel_stats | Pixel stats (events, match rate, CAPI health). | | meta_ads_list_lead_forms | List lead gen forms from a Page. | | meta_ads_get_leads | Get captured leads from a form. | | meta_ads_list_audiences | List custom and lookalike audiences. | | meta_ads_list_catalogs | List product catalogs. | | meta_ads_list_product_sets | List product sets from a catalog. | | meta_ads_get_feed_status | Check product feed upload status. | | meta_ads_export_report | Generate formatted performance report (markdown). |

Audiences (5 tools)

| Tool | Description | |------|-------------| | meta_ads_create_custom_audience | Create custom audience (website, engagement, customer list). | | meta_ads_upload_customer_list | Upload customer data with auto SHA-256 hashing. | | meta_ads_create_lookalike_audience | Create lookalike from source audience. | | meta_ads_delete_audience | Delete audience (irreversible). | | meta_ads_validate_whatsapp | Validate WhatsApp number for Click-to-WhatsApp ads. |

Catalog (3 tools)

| Tool | Description | |------|-------------| | meta_ads_create_catalog | Create product catalog in Business Manager. | | meta_ads_create_product_feed | Create product feed (CSV, XML, TSV URL). | | meta_ads_create_product_set | Create product set for Dynamic Product Ads. |

Smart Ops (5 tools)

| Tool | Description | |------|-------------| | meta_ads_batch_update_status | Batch status update (up to 50 per request). | | meta_ads_get_adset_pacing | Budget pacing analysis (underspend/overspend). | | meta_ads_smart_pause | Auto-pause by name filter or expiration date. | | meta_ads_generate_name | Generate standardized names (naming convention). | | meta_ads_manage_accounts | Manage accounts.json (list, add, edit, remove). |

Google Ads Tools (34)

Campaigns (6 tools)

| Tool | Description | |------|-------------| | google_ads_list_accounts | List all accounts accessible via MCC. | | google_ads_list_campaigns | List campaigns with metrics. | | google_ads_create_budget | Create CampaignBudget (required before campaign). | | google_ads_create_campaign | Create campaign (always PAUSED). | | google_ads_update_campaign | Update campaign fields. | | google_ads_update_status | Change status (ENABLED/PAUSED/REMOVED) in batch. |

Ad Groups (5 tools)

| Tool | Description | |------|-------------| | google_ads_list_ad_groups | List ad groups with metrics. | | google_ads_create_ad_group | Create ad group (PAUSED by default). | | google_ads_update_ad_group | Update ad group fields. | | google_ads_create_ad | Create ad (RSA or Responsive Display). | | google_ads_update_ad | Update ad status. |

Keywords (5 tools)

| Tool | Description | |------|-------------| | google_ads_list_keywords | List keywords with performance metrics. | | google_ads_get_search_terms | Search terms report — what people actually searched. | | google_ads_add_keywords | Add positive keywords (batch). | | google_ads_add_negative_keywords | Add negative keywords (campaign or ad group). | | google_ads_get_keyword_ideas | Generate keyword ideas from seeds or URL. |

Reporting (5 tools)

| Tool | Description | |------|-------------| | google_ads_query | Execute any GAQL query (most flexible reporting). | | google_ads_list_resources | List available GAQL resources and fields. | | google_ads_get_insights | Performance metrics by level (campaign, ad group, ad, keyword). | | google_ads_export_report | Generate formatted markdown report. | | google_ads_get_change_history | Account change history (who changed what). |

Audiences (4 tools)

| Tool | Description | |------|-------------| | google_ads_list_audiences | List user lists (remarketing, custom). | | google_ads_create_audience | Create user list. | | google_ads_add_targeting | Apply targeting (audience, demo, geo) to ad group. | | google_ads_upload_customer_list | Upload Customer Match list (auto SHA-256). |

Assets (4 tools)

| Tool | Description | |------|-------------| | google_ads_list_assets | List assets (images, videos, sitelinks). | | google_ads_analyze_assets | Analyze asset performance. | | google_ads_upload_image | Upload image asset (base64). | | google_ads_create_video_asset | Create video asset from YouTube URL. |

Smart Ops (5 tools)

| Tool | Description | |------|-------------| | google_ads_batch_update | Atomic batch mutations (up to 10,000 ops). | | google_ads_smart_pause | Auto-pause underperforming campaigns/ad groups. | | google_ads_generate_name | Generate standardized campaign names. | | google_ads_account_audit | Audit account structure (naming, budget, orphans). | | google_ads_manage_accounts | Manage Google Ads accounts config. |

Credentials

Meta Ads — System User Token

Get from Meta Business Manager:

1. Go to Business Settings → System Users → Generate Token
2. Select permissions: ads_management, ads_read, business_management, pages_read_engagement
3. Copy the token

Token is passed via META_ADS_ACCESS_TOKEN env variable.

Google Ads — OAuth2

Required credentials:

• GOOGLE_ADS_DEVELOPER_TOKEN — from Google Ads API Center
• GOOGLE_ADS_CLIENT_ID — OAuth2 client ID
• GOOGLE_ADS_CLIENT_SECRET — OAuth2 client secret
• GOOGLE_ADS_REFRESH_TOKEN — OAuth2 refresh token
• GOOGLE_ADS_LOGIN_CUSTOMER_ID — MCC account ID (optional)

Safety

• All ads created as PAUSED — never active directly
• Meta budget cap: R$5,000/day (hardcoded)
• Rate limiter: 200 calls/hour per ad account
• Auto-retry with exponential backoff on rate limits
• Tokens never logged to stdout (MCP stdio protocol)
• Customer data auto-hashed with SHA-256

Updating

If installed via npx, just restart Claude Desktop to get the latest version.

If installed from source:

cd media-buyer-plugin
git pull && npm install && npm run build

Troubleshooting

| Problem | Solution | |---------|----------| | Tools not appearing | Restart Claude Desktop after config change | | "META_ADS_ACCESS_TOKEN not set" | Check token in your Claude Desktop config | | "Token is invalid or expired" | Generate new token in Business Manager | | "Permission denied" | Check token scopes (ads_management, ads_read, business_management) | | Google Ads "Missing credentials" | Check all 4 env vars are set in config | | Build failed | Verify Node.js 20+ (node -v) and run npm install |

Architecture

media-buyer-plugin/
├── src/
│   ├── index.ts              # Meta Ads entry point (stdio)
│   ├── server.ts             # Meta MCP server (45 tools)
│   ├── meta-client.ts        # Meta API client
│   ├── tools/                # Meta tools (core, read, audiences, catalog, smart-ops)
│   ├── lib/                  # HTTP client, rate limiter, errors
│   ├── schemas/              # Zod schemas
│   └── google/
│       ├── index.ts          # Google Ads entry point (stdio)
│       ├── server.ts         # Google MCP server (34 tools)
│       ├── google-client.ts  # Google Ads API client
│       ├── tools/            # Google tools (campaigns, ad-groups, keywords, reporting, audiences, assets, smart-ops)
│       ├── lib/              # Auth (OAuth2), HTTP client, errors
│       └── schemas/          # Google Ads schemas
├── dist/                     # Compiled output
├── config/
│   ├── setup.sh              # Interactive setup (token + accounts + MCP)
│   └── accounts.example.json # Account mapping template
├── agents/                   # Agent definitions
├── skills/                   # Skill definitions (create-ad, manage)
└── tests/                    # Vitest test suite

Built by KV Consulting