io.github.Mike25app/scaleforge-mcp-meta-ads

Official

by Mike25app · TypeScript

Meta Ads MCP by ScaleForge — control Facebook & Instagram Ads via Graph API v24.0. 32 tools.

Control Facebook and Instagram ads programmatically via Meta Graph API.

Topics

ai-agentanthropicautomationclaudefacebook-adsllm-toolsmcpmcp-servermeta-adsmodel-context-protocolscaleforge

README.md18 KBView on GitHub

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:

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.
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.
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.
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.
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)

bash

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

bash

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):

json

{
  "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):

json

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

Local test (no client setup)

bash

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

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

bash

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

Architecture

code

┌──────────────┐       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.

Open the Graph API Explorer.
In the User or Page dropdown, select User Token.
Click Add a Permission and select: ads_management, ads_read, business_management, pages_read_engagement, pages_manage_ads.
Click Generate Access Token and approve the dialog.
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.

Create a Facebook App (if you don't have one) at developers.facebook.com/apps. Any app works — Business type is fine.
Create a Business Manager at business.facebook.com. You need this as the container for your System User.
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.)
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]
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]
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]
Click Generate and copy the token. It never expires. Store it in a secret manager / env var / password manager.

Now use it:

bash

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

Meta pain point	How this MCP handles it
Rate limit code #17 in bulk ops	`pause_campaigns_batch`, `activate_campaigns_batch`, `update_bids_batch` use Meta Batch API (up to 50 ops/request) with auto-chunking and a 2s gap between chunks.
250-ads-per-Page silent cap	`get_ads_volume` + automatic pre-flight check inside `activate_campaigns_batch` — warnings come back in the response before Meta starts any review.
Token-expired errors	`enhanceMetaError` detects codes 190 / 102 / 104 / 463 / 467 and returns a message pointing to the stable-token setup.
Instagram placements without IG login	`get_pbia` auto-creates a Page-Backed Instagram Account and returns the `instagram_user_id` for your `object_story_spec`.
v22 deprecations	Uses `instagram_user_id`, no `degrees_of_freedom_spec`, no `asset_feed_id`.
Image hash scoping	Documented on `upload_image` + `create_ad_creative` — hashes are per-account, you must re-upload to each target account. (Cached per-account caching logic lives in ScaleForge's backend and will be added here in a later release.)

Tools reference

32 tools across 10 categories.

Accounts (3)

Name	Purpose
`list_ad_accounts`	List Ad Accounts accessible to the token
`get_ad_account`	Detailed info for one account (status, spend cap, balance)
`get_ads_volume`	Per-Page running-ads count + limit + remaining slots (pre-flight check)

Campaigns (5)

Name	Purpose
`list_campaigns`	Paginated campaign list
`get_campaign`	Single campaign by ID
`create_campaign`	WRITE — create new campaign (defaults to PAUSED)
`update_campaign`	WRITE — update any mutable field
`delete_campaign`	WRITE — hard delete

Ad Sets (5)

Name	Purpose
`list_adsets`	List by ad_account_id OR campaign_id
`get_adset`	Single ad set by ID
`create_adset`	WRITE — create ad set under a campaign
`update_adset`	WRITE — update targeting, bid, budget, status
`delete_adset`	WRITE — hard delete

Ads (4)

Name	Purpose
`list_ads`	List by ad_account_id, adset_id, or campaign_id
`get_ad`	Single ad by ID (incl. creative + issues + preview link)
`update_ad`	WRITE — update name, status, swap creative
`delete_ad`	WRITE — hard delete

Creatives (4)

Name	Purpose
`list_creatives`	List all creatives in an ad account
`get_creative`	Single creative by ID
`create_ad_creative`	WRITE — single-text creative via `object_story_spec`
`create_ad_creative_with_asset_feed`	WRITE — dynamic/multi-text creative via `asset_feed_spec`

Media (2)

Name	Purpose
`upload_video`	WRITE — upload video via remote URL (returns video_id)
`upload_image`	WRITE — upload image via remote URL (returns image_hash, scoped to account)

Insights (3)

Name	Purpose
`get_campaign_insights`	Metrics at campaign level with breakdowns
`get_adset_insights`	Metrics at ad set level
`get_ad_insights`	Metrics at ad level (compare creatives)

Bulk (3)

Name	Purpose
`pause_campaigns_batch`	WRITE (BULK) — pause many campaigns via Batch API
`activate_campaigns_batch`	WRITE (BULK) — activate many + pre-flight ads_volume check
`update_bids_batch`	WRITE (BULK) — update `bid_amount` on many ad sets

Pages (2)

Name	Purpose
`list_pages`	Facebook Pages the token can manage
`get_pbia`	Get or auto-create a Page-Backed Instagram Account

Ads Library (1)

Name	Purpose
`search_ads_library`	Public Meta Ad Library search for competitive research

Example prompts

Once the server is connected, try these in your agent.

Read-only

"List my Meta ad accounts and show me which ones are active, currency, and spend cap."
"For campaign 1234567890, pull last_14d insights with breakdown by placement — which placement has the lowest CPL?"
"Show me the ads_volume for account act_555 — any Page over 85% of its limit?"
"Search the Meta Ad Library for ads from Competitor X running in the US in the last month."
"List all ad sets in campaign ABCD and show which ones have is_dynamic_creative=true."

Write (confirm first)

Write operations change live Meta Ads state — spend starts or stops immediately. A well-behaved agent (Claude, GPT-4) will show you the target list and ask "proceed?" before calling these.

"Pause campaigns 111, 222, 333 — show me their names and current spend first, then pause."
"Activate campaigns 444 and 555. Run the ads_volume pre-flight first; if any Page is over 85%, abort and tell me which."
"Bump the bid on ad sets 6001 and 6002 to $4.50. Convert to cents for me."
"Create a new campaign in act_777 called 'Spring Promo Test', OUTCOME_LEADS objective, daily_budget 5000 cents, PAUSED."

FAQ

How do I get a Meta access token?

See Get a Meta Access Token above. Two options: quick 2-hour token (Graph API Explorer) or stable System User token (Business Manager, never expires).

Why does my token keep expiring?

You're using a User access token from the Graph API Explorer. Those expire in ~2 hours by design. For anything beyond experimentation, generate a System User token via Business Manager — those never expire. Full steps here.

What's ads_volume?

Meta limits how many ads can be "running or in review" per Facebook Page — default 250 — and this limit is shared across every ad account using that Page. The get_ads_volume tool shows you how much headroom each Page has. activate_campaigns_batch calls it automatically as a pre-flight check.

Is this free?

Yes. MIT license, npm package is free. You pay Meta for ads as usual. There is no ScaleForge account or subscription needed to use this MCP.

How does this compare to Pipeboard / other MCPs?

Pipeboard / hosted MCPs — run on their server, you send your token to them, they rate-limit you. Fine for very light usage, but the token lives on someone else's machine.
This MCP — runs locally, your token never leaves your box, direct path to Meta. 32 tools (more coverage than any other Meta MCP we've seen).
ScaleForge managed platform (see below) — a separate product for teams that want managed Meta access, RedTrack integration, scheduled auto-rules, UI dashboards. This MCP is a standalone tool that does not depend on it.

Can I use this without ScaleForge?

Yes. This MCP is a standalone npm package — it talks straight to graph.facebook.com. No account anywhere.

Can I contribute more tools?

Please do. PRs welcome at github.com/Mike25app/scaleforge-mcp-meta-ads. Each tool is a small file in src/tools/ — copy one of the existing files as a template.

Powered by ScaleForge

Built and maintained by the ScaleForge team. If you need managed Meta access (System User provisioning, RedTrack integration, scheduled auto-rules, dashboards), check out the full platform — this MCP stays free and standalone regardless.

Security

Generate least-privilege tokens. Scope your System User to only the ad accounts + Pages it needs. Revoking a token takes effect immediately.
Never commit tokens to source control. The MCP reads from META_ACCESS_TOKEN env var — keep it in your agent host's secret store (Claude Desktop's env block, shell profile with 600 perms, 1Password, etc.).
Rotate periodically. Even non-expiring System User tokens should be rotated on a team policy. Regenerating in Business Manager invalidates the old one.
No telemetry. This MCP does not phone home. The only outbound requests it makes are to https://graph.facebook.com/v24.0/*.
Rate limits apply per token / per ad account (Meta-side). Bulk tools automatically use Meta Batch API to stay under.

License

MIT — see LICENSE.

Install

Configuration

Environment variables

META_ACCESS_TOKENrequiredsecret

Meta Marketing API token (System User or Graph API Explorer). See README.

claude_desktop_config.json

{
  "mcpServers": {
    "scaleforge-mcp-meta-ads": {
      "command": "npx",
      "args": [
        "-y",
        "@getscaleforge/mcp-meta-ads@0.2.3"
      ],
      "env": {
        "META_ACCESS_TOKEN": "<YOUR_META_ACCESS_TOKEN>"
      }
    }
  }
}

Topics

Meta Ads MCP by ScaleForge

The problem

The solution

Hosted endpoint (no install)

Quick start — pick one

Smithery (easiest, auto-configures the client)

Claude Code CLI

Claude Desktop (manual JSON config)

Cursor

Local test (no client setup)

Architecture

Get a Meta Access Token

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

Option 2 — Stable token (never expires) <a id="stable-tokens"></a>

Baked-in pain point fixes

Tools reference

Accounts (3)

Campaigns (5)

Ad Sets (5)

Ads (4)

Creatives (4)

Media (2)

Insights (3)

Bulk (3)

Pages (2)

Ads Library (1)

Example prompts

Read-only

Write (confirm first)

FAQ

How do I get a Meta access token?

Why does my token keep expiring?

What's ads_volume?

Is this free?

How does this compare to Pipeboard / other MCPs?

Can I use this without ScaleForge?

Can I contribute more tools?

Powered by ScaleForge

Security

Links

License

Install

Configuration