Skip to main content
Glama
scaleforge-mcp-meta-ads

scaleforge-mcp-meta-ads

by Mike25app

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.

npm license Node


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.

Related MCP server: facebook-business-mcp

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. A request with no token at all gets 401 with an OAuth challenge (sign in with ScaleForge — see below).

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


ScaleForge data tools — analyse the competitor ads you saved

Optional second tool group (since 0.4.0). If you scan competitors in Facebook Ad Library with the FB Ads Library Scraper Pro Chrome extension and click Save to ScaleForge, Claude can read those scans and analyse them on your own Claude plan — e.g. "analyse the last 100 ads of competitor X", "what's new in my Watchlist?", "what did Acme launch since last week?".

One click, no token (claude.ai, Claude Desktop, mobile, Claude Code). The hosted endpoint speaks OAuth 2.1: ScaleForge is the authorization server, and a request without credentials gets 401 WWW-Authenticate: Bearer resource_metadata=…, so Claude opens the ScaleForge sign-in window by itself.

  • claude.ai: click Connect to Claude at getscaleforge.com/connect/claude — claude.ai opens with the connector filled in → Add → Connect → Allow in the ScaleForge window. Or add a custom connector with the URL https://getscaleforge.com/mcp by hand.

  • Claude Code: claude mcp add --scope user --transport http scaleforge https://getscaleforge.com/mcp, then /mcp → scaleforge → Authenticate.

Two entrances on the same server:

URL

Shown in Claude as

Tools

https://getscaleforge.com/mcp

ScaleForge

ScaleForge data tools (+ Meta Ads tools when a Meta token is sent)

https://getscaleforge.com/mcp/scraper

FB Ads Library Scraper Pro by ScaleForge

saved scans + Watchlist only

Signed in through OAuth (an sf_ token only), /mcp lists just the ScaleForge data tools — Meta Ads tools need a Meta token. Access tokens live 1 hour and are refreshed automatically; a revoked or expired token gets 401 error="invalid_token" (checked against GET /oauth/token_info, cached for a minute).

Manual token (other MCP clients):

  1. Sign in at getscaleforge.com/connect/claude → For developers → Create token. The token is read-only (scans:read, hunted_creatives:read, watchlist:read) and starts with sf_.

  2. Connect — pick one:

# Claude Code, hosted endpoint (nothing to install)
claude mcp add --transport http scaleforge https://getscaleforge.com/mcp \
  --header "Authorization: Bearer sf_YOUR_TOKEN"

# Claude Code, local stdio
claude mcp add scaleforge --env SCALEFORGE_API_TOKEN=sf_YOUR_TOKEN -- npx -y @getscaleforge/mcp-meta-ads

Claude Desktop (claude_desktop_config.json):

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

Both tokens can live in one server: add META_ACCESS_TOKEN next to SCALEFORGE_API_TOKEN (stdio), or send Authorization: Bearer <meta token> plus X-ScaleForge-Token: sf_… (hosted). On the hosted endpoint a Bearer token that starts with sf_ is treated as the ScaleForge token; ?scaleforgeApiToken= (Smithery config) also works. Without a ScaleForge token these tools answer with instructions instead of failing; Meta tools are unaffected. SCALEFORGE_API_URL overrides the API base (default https://getscaleforge.com) for local development; SCALEFORGE_PUBLIC_URL overrides the public origin used in the OAuth resource URLs.

Prompt analyze_competitor_ads (args: competitor, scan_id, ads_count, language) packages the analysis method: probable winners (longest-running active ads), hooks, offers, angles, CTAs, landing pages, testing pattern and 5 new ad ideas. In Claude Code: /mcp__scaleforge__analyze_competitor_ads.


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

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

38 tools across 11 categories — 32 Meta Ads tools + 6 ScaleForge data tools.

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

ScaleForge data (6, read-only, needs SCALEFORGE_API_TOKEN)

Name

Purpose

list_my_scans

Saved Ad Library scans (advertiser or keyword), newest first; query filter

get_scan

One scan with its ads, trimmed for context (max_ads, offset, sort, only_new, status, max_text_chars, dedupe_text, include_media_urls) + stats over all ads

compare_scans

New / gone / still-running ads vs the previous scan of the same query

list_hunted_creatives

Ads bookmarked with Hunter

list_watchlist

Watched competitor Pages with last re-scan counts

get_watchlist_ads

Ads of one Watchlist item (new_only)


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 — the Meta tools talk straight to graph.facebook.com. No account anywhere. Only the optional ScaleForge data tools need a ScaleForge account (they read the scans you saved there).

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. Meta tools only call https://graph.facebook.com/v24.0/*; ScaleForge data tools call https://getscaleforge.com/api/v1/* and only when you configured a ScaleForge token.

  • Rate limits apply per token / per ad account (Meta-side). Bulk tools automatically use Meta Batch API to stay under.



License

MIT — see LICENSE.

Available Tools

32 tools
activate_campaigns_batchA

WRITE (BULK): Activate many campaigns in one Batch API call. BEFORE activation we run a per-Page ads_volume pre-flight for every distinct ad account — warnings are returned in the response so the agent / user can abort if a Page is over capacity. Agents MUST confirm with the user before calling this (activation starts spend immediately).

Inputs: campaign_ids (required), skip_preflight.

create_ad_creativeA

WRITE: Create a single-text ad creative from an object_story_spec. Pass page_id plus ONE of: video_data (for video ads — needs video_id from upload_video), link_data (for image / link ads — needs image_hash from upload_image + link + message). If the Page is not linked to Instagram, pass instagram_user_id from get_pbia() to enable IG placements.

Note: image hashes are per-ad-account in Meta — a hash uploaded on account A is NOT valid on account B. Re-upload to each target account.

Inputs: ad_account_id (required), name (required), page_id (required), instagram_user_id, +9 more.

create_ad_creative_with_asset_feedA

WRITE: Create a DYNAMIC (multi-text) creative using asset_feed_spec. Meta will auto-combine the bodies/titles/descriptions and optimize the best mix. The parent ad set MUST have is_dynamic_creative=true. Pass arrays of texts plus either video_id(s) or image_hash(es).

Inputs: ad_account_id (required), name (required), page_id (required), bodies (required), +8 more.

create_adsetA

WRITE: Create an ad set under a campaign. Default status is PAUSED. targeting is a Meta targeting spec object (geo_locations, age_min, age_max, interests, etc.). bid_amount is in account currency minor units (cents). For multi-text / dynamic creative ads you MUST set is_dynamic_creative=true — otherwise asset_feed_spec ads will be rejected.

Inputs: ad_account_id (required), campaign_id (required), name (required), targeting (required), +11 more.

create_campaignA

WRITE: Create a new campaign. Default status is PAUSED (recommended — set ACTIVE only after creating ad sets and ads). For CBO, pass daily_budget or lifetime_budget at this level; for ABO leave budget off and set it on the ad set. special_ad_categories is required (empty array [] is fine for normal advertising).

Inputs: ad_account_id (required), name (required), objective (required), status, +5 more.

delete_adA

WRITE: Hard-delete an ad. Prefer update_ad status=ARCHIVED to keep history.

Inputs: ad_id (required).

delete_adsetA

WRITE: Hard-delete an ad set (and its ads). Prefer update_adset status=ARCHIVED to keep history.

Inputs: adset_id (required).

delete_campaignA

WRITE: Hard-delete a campaign (and its ad sets / ads). Prefer update_campaign with status=ARCHIVED if you want to keep historical data.

Inputs: campaign_id (required).

get_adA

Get a single ad by ID. Returns full creative + issues + preview link.

Inputs: ad_id (required), fields.

get_ad_accountA

Get detailed info for a single Ad Account: status, spend cap, balance, funding source, business, timezone, disable_reason. Returns the full configuration record — use this for deep inspection of one account.

Inputs: ad_account_id (required), fields.

get_ad_insightsA

Pull performance metrics for ONE ad. Same fields/breakdowns as get_campaign_insights. Use this to compare creative performance at the individual-ad level.

Inputs: ad_id (required), date_preset, time_range, breakdowns, +6 more.

get_adsetA

Get a single ad set by ID. Returns default fields plus anything in fields.

Inputs: adset_id (required), fields.

get_adset_insightsB

Pull performance metrics for ONE ad set. Same fields/breakdowns as get_campaign_insights.

Inputs: adset_id (required), date_preset, time_range, breakdowns, +6 more.

get_ads_volumeA

PRE-FLIGHT CHECK: Get per-Page ads-running-or-in-review counts and limits for an ad account. Meta caps active ads per Page (default 250) and this limit is SHARED across every account using the same Page. Always call this before a bulk activation to avoid silent review failures. Returns one row per Page actor.

Inputs: ad_account_id (required).

get_campaignA

Get a single campaign by ID. Returns all default fields plus anything in fields. Use this for deep inspection of one campaign.

Inputs: campaign_id (required), fields.

get_campaign_insightsA

Pull performance metrics for ONE campaign. Default fields: spend, impressions, clicks, cpc, cpm, ctr, reach, frequency, actions, conversions, purchase_roas. Default range: last_7d. Use breakdowns for cuts (age, gender, country, placement). Use time_increment=1 for day-by-day rows.

Inputs: campaign_id (required), date_preset, time_range, breakdowns, +6 more.

get_creativeB

Get a single ad creative by ID.

Inputs: creative_id (required), fields.

get_pbiaA

Get (or auto-create) a Page-Backed Instagram Account for a Facebook Page. Use this when the Page has no linked Instagram account but you want to run ads with IG placements — Meta lets a Page act as its own IG presence via PBIA (same option as 'Use Facebook Page for Instagram' in Ads Manager).

Flow: GET the Page's access_token, list existing PBIAs, create one if none exists. Returns {page_backed_instagram_account_id, created (bool)}.

Inputs: page_id (required).

list_ad_accountsA

List Meta Ad Accounts accessible to the current access token. Returns id (act_XXX), name, account_status, currency, business_name, spend_cap, timezone_name. Use this first to discover what you can work with.

Inputs: limit, after.

list_adsB

List ads. Pass either ad_account_id (all ads in account), adset_id (ads in one ad set), or campaign_id (ads in a campaign). Returns id, name, adset_id, creative, status.

Inputs: ad_account_id, adset_id, campaign_id, limit, +3 more.

list_adsetsA

List ad sets. Pass either ad_account_id (lists all adsets in account) OR campaign_id (lists adsets of one campaign). Returns id, name, campaign_id, status, daily_budget, bid_amount, billing_event, optimization_goal, targeting, is_dynamic_creative.

Inputs: ad_account_id, campaign_id, limit, after, +2 more.

list_campaignsA

List campaigns in an ad account. Returns id, name, status, objective, daily_budget, lifetime_budget, bid_strategy, created_time. Paginated via limit + after cursor.

Inputs: ad_account_id (required), limit, after, effective_status, +1 more.

list_creativesB

List ad creatives in an account. Returns id, name, object_story_spec, asset_feed_spec, thumbnail_url, video_id, image_hash, body/title.

Inputs: ad_account_id (required), limit, after, fields.

list_pagesA

List Facebook Pages the current user/System User manages. Each row has id, name, access_token (Page Access Token — needed for PBIA provisioning), category, tasks (what this token can do on the Page, e.g. 'MANAGE', 'CREATE_CONTENT', 'ADVERTISE').

Inputs: limit, after.

pause_campaigns_batchA

WRITE (BULK): Pause many campaigns in a single Meta Batch API call (up to 50/request; arrays bigger than 50 are chunked automatically with a 2s delay between chunks to sidestep rate-limit code 17). Returns {results: Array<{code, body}>} — one entry per campaign. code: 200 = success.

Inputs: campaign_ids (required).

search_ads_libraryA

Search Meta's public Ad Library for competitive research. Returns active and inactive ads matching search_terms OR search_page_ids in the selected countries. Default country = ['US']. Returns ad_snapshot_url (preview), creative bodies/titles, page_id, delivery times, publisher_platforms.

Note: only ads in categories subject to public transparency (political / housing / employment / credit) return full metadata; other categories return lighter data.

Inputs: search_terms, search_page_ids, ad_reached_countries, ad_type, +5 more.

update_adA

WRITE: Update an ad's name, status, or swap its creative. To replace the creative pass creative: {creative_id: 'XXX'}.

Inputs: ad_id (required), name, status, creative.

update_adsetA

WRITE: Update any mutable field on an ad set (status, bid_amount, daily_budget, targeting, name, etc.). Pass only the fields you want to change.

Inputs: adset_id (required), name, status, bid_amount, +7 more.

update_bids_batchA

WRITE (BULK): Update bid_amount on many ad sets in one Batch API call. Input is an array of {adset_id, bid_amount_cents} pairs. Bid values are in minor currency units (cents). Chunks of 50 automatically.

Inputs: updates (required).

update_campaignC

WRITE: Update any mutable field on a campaign (name, status, daily_budget, lifetime_budget, bid_strategy). Pass only the fields you want to change.

Inputs: campaign_id (required), name, status, daily_budget, +3 more.

upload_imageA

WRITE: Upload an image to an ad account. Returns {images: {filename: {hash}}}. The hash is what you pass to create_ad_creative as image_hash.

IMPORTANT: Meta image hashes are SCOPED TO THE AD ACCOUNT — a hash uploaded on account A cannot be used on account B. If you need the same image across multiple accounts, call this once per account. (ScaleForge's backend caches hashes per account to avoid re-uploads within the same account.)

Inputs: ad_account_id (required), url, filename.

upload_videoA

WRITE: Upload a video to an ad account. Returns {id, title}. Prefer file_url (remote URL Meta fetches server-side) — streaming a local file over MCP stdio is awkward and rarely needed when videos live in S3 / Dropbox / a CDN. Local file_path is accepted for completeness but may be blocked on Windows / sandboxed MCP hosts.

Inputs: ad_account_id (required), file_url, file_path, title, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 32 tools

    Disambiguation5/5

    Each tool targets a distinct resource and operation. Lists, gets, creates, updates, deletes, batch operations, and special utilities are clearly separated. Even similar operations like get_ad vs get_ad_insights are differentiated by purpose. No significant overlap.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., list_ad_accounts, create_campaign, update_bids_batch). Minor exceptions like get_pbia are justified by acronyms. The naming is predictable and easy to navigate.

    Tool Count5/5

    32 tools might seem high, but the Meta Ads domain is complex, requiring tools for CRUD on multiple entities, batch operations, insights, pre-flight checks, and competitive research. Each tool serves a clear, non-redundant purpose, making the count appropriate.

    Completeness5/5

    The tool surface covers the full lifecycle: campaign, ad set, ad, and creative CRUD; listing and detail retrieval; batch operations; image/video upload; insights; account and page management; pre-flight checks; and competitive search. No obvious gaps exist for standard ad management workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A Model Context Protocol server that allows AI models to access, analyze, and manage Meta advertising campaigns, enabling LLMs to retrieve performance data, visualize ad creatives, and provide strategic insights for Facebook and Instagram platforms.
      35
      1,368
      Business Source 1.1
    • A
      license
      Not graded
      quality
      D
      maintenance
      Unofficial MCP server implementation for Facebook Business API. Enables LLMs to manage ad campaigns and ads via natural language.
      27 PyPI
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A Model Context Protocol server for the Meta (Facebook) Ads API, providing 54 tools to manage ad accounts, campaigns, ad sets, ads, creatives, media, insights, targeting, and more via the Meta Graph API.
      35
      17
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A Model Context Protocol server that lets AI assistants run your Meta Ads end to end — launch campaigns, upload creatives, update budgets, and dig into performance through natural conversation. Works across Facebook, Instagram, and other Meta surfaces.
      Business Source 1.1