Meta Ads Mcp 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) <a id="stable-tokens"></a>

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.

…