Meta Ads MCP by ScaleForge

Control Facebook & Instagram Ads from Claude, ChatGPT, Cursor, or any MCP-compatible agent.

Direct Meta Graph API v24.0 wrapper. 32 tools. No backend required — just bring your own Meta access token.

The problem

Meta's Marketing API is powerful but punishing. Anyone who's tried to automate Meta Ads has run into these five walls:

1. Rate-limit whack-a-mole (error code #17). Your script hits User request limit reached halfway through a launch and leaves campaigns in a half-configured state. Meta's per-account budget of calls resets over 5 minutes, but nothing in the API tells you that without context.
2. Token expiry chaos. User access tokens from the Graph API Explorer die every ~2 hours. You fix a bug, come back from lunch, and every request is suddenly (#190) Error validating access token.
3. v22 → v24 deprecations (Sept 2025). instagram_actor_id → instagram_user_id, degrees_of_freedom_spec is gone entirely, asset_feed_id has been deprecated since v3.1. Copy-pasted sample code from Stack Overflow breaks silently.
4. Image hashes are per-ad-account. An image uploaded on Account A cannot be used on Account B — you get Image Not Found on the second account. Video IDs are global, but image hashes are not. This trips up 100% of first-time multi-account automations.
5. The 250-ads-per-Page cap. Meta limits ads-running-or-in-review per Page (not per account) — and this limit is shared across every account using that Page. Overshoot and the 251st ad silently fails review.

The solution

This MCP is a thin, typed wrapper over Meta's Graph API with those five pains baked out:

• Auto-batch for bulk ops (pause_campaigns_batch, activate_campaigns_batch, update_bids_batch) — up to 50 ops per HTTP request, chunked automatically. Sidesteps rate-limit code #17 for bulk work.
• Pre-flight ads_volume check before every bulk activation — warns you when a Page is near the 250-ad cap, per ad account, before Meta silently fails the reviews.
• Enhanced error messages with actionable links — when your token expires or a rate limit fires, the MCP tells your agent exactly what to do (create a System User token, wait 5 min, etc.).
• v24.0 everywhere — current field names, no deprecated spec shapes.
• PBIA auto-provisioning (get_pbia) — when a Page has no linked Instagram account, the MCP creates a Page-Backed Instagram Account on demand so IG placements work.

No ScaleForge backend is in the chain. Your agent → this MCP → https://graph.facebook.com/v24.0/*. That's it.

Hosted endpoint (no install)

Use the ScaleForge-hosted Streamable HTTP endpoint — zero install, nothing to run locally:

• Smithery listing: https://smithery.ai/server/kirichyk-misha/meta-ads (one-click install for Claude Desktop, Cursor, Windsurf, Continue, ChatGPT Desktop — Smithery prompts for your Meta token, writes the config).
• Direct URL for custom clients: https://getscaleforge.com/mcp (MCP Streamable HTTP). Supply your token via Smithery session config or Authorization: Bearer <token> header.

Prefer a local npm install? Use the stdio package below.

Quick start — pick one

Smithery (easiest, auto-configures the client)

npx -y @smithery/cli install @getscaleforge/mcp-meta-ads --client claude
# also: --client cursor | --client windsurf | --client continue

Smithery will prompt you for the Meta access token and write the config file.

Claude Code CLI

claude mcp add scaleforge \
  --env META_ACCESS_TOKEN=YOUR_TOKEN \
  -- npx -y @getscaleforge/mcp-meta-ads

Verify with claude mcp list.

Claude Desktop (manual JSON config)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or the Windows / Linux equivalent — Claude Desktop creates it if missing):

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@getscaleforge/mcp-meta-ads"],
      "env": {
        "META_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

Restart Claude Desktop. The 32 tools appear under the hammer icon.

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@getscaleforge/mcp-meta-ads"],
      "env": { "META_ACCESS_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}

Local test (no client setup)

META_ACCESS_TOKEN=YOUR_TOKEN npx -y @getscaleforge/mcp-meta-ads

The server starts on stdio. Poke it interactively with @modelcontextprotocol/inspector:

npx -y @modelcontextprotocol/inspector \
  env META_ACCESS_TOKEN=YOUR_TOKEN npx -y @getscaleforge/mcp-meta-ads

Architecture

┌──────────────┐       MCP stdio        ┌───────────────────┐    HTTPS + OAuth token    ┌──────────────────────┐
│ Claude / GPT │ ◄────────────────────► │  mcp-meta-ads     │ ◄───────────────────────► │  Meta Graph API v24  │
│   Cursor     │   JSON-RPC over stdio  │  (this package)   │   graph.facebook.com      │  Marketing API       │
│ ChatGPT Desk │                        │                   │                           │                      │
└──────────────┘                        └───────────────────┘                           └──────────────────────┘

The MCP is a thin, typed translation layer. It does not cache, does not proxy, does not phone home. Every call goes from your machine straight to Meta's servers with your token.

Get a Meta Access Token

You need an access token with ads_management, ads_read, business_management, and (for Page-scoped work like PBIA provisioning) pages_read_engagement + pages_manage_ads.

There are two kinds of tokens. Pick based on your use case.

Option 1 — Quick token (2 minutes, expires in ~2 hours)

Good for: trying the MCP, quick experiments, one-off scripts.

1. Open the Graph API Explorer.
2. In the User or Page dropdown, select User Token.
3. Click Add a Permission and select: ads_management, ads_read, business_management, pages_read_engagement, pages_manage_ads.
4. Click Generate Access Token and approve the dialog.
5. Copy the token at the top. That's your META_ACCESS_TOKEN.

The token expires in ~2 hours. When it dies, the MCP will return an enhanced error pointing you here.

Option 2 — Stable token (never expires)

Good for: production, scheduled jobs, anything you don't want to re-auth every 2 hours.

You generate a System User token inside Meta Business Manager. System User tokens have no expiry and can be scoped to specific assets (ad accounts + Pages). This is the same token type ScaleForge and every production Meta integration uses.

1. Create a Facebook App (if you don't have one) at developers.facebook.com/apps. Any app works — Business type is fine.
2. Create a Business Manager at business.facebook.com. You need this as the container for your System User.
3. Add your ad accounts and Pages to the Business under Business Settings → Accounts → Ad Accounts / Pages. (If they're owned by another Business, request access.)
4. Create a System User: Business Settings → Users → System Users → Add → name it (e.g. mcp-meta-ads) → role Admin. [screenshot: Business Settings → Users → System Users tab with "Add" button]
5. Assign ad accounts to the System User: click the System User → Add Assets → pick Ad Accounts → select yours → turn on Manage permission. Repeat for Pages. [screenshot: Add Assets dialog with "Manage" toggle highlighted]
6. Generate the token: click Generate New Token → select your Facebook App → pick scopes:
   • ads_management
   • ads_read
   • business_management
   • pages_read_engagement
   • pages_manage_ads
   • read_insights (optional — needed for some insight breakdowns) [screenshot: Generate Token dialog with scopes checklist]
7. Click Generate and copy the token. It never expires. Store it in a secret manager / env var / password manager.

Now use it:

META_ACCESS_TOKEN=EAAB...your-token... npx -y @getscaleforge/mcp-meta-ads

If you revoke or regenerate later, the old token stops working immediately.

Baked-in pain point fixes

Tools reference

32 tools across 10 categories.