scaleforge-mcp-meta-ads
You can manage and analyze Facebook/Instagram ads end-to-end through this MCP server.
Discover and inspect ad accounts, Pages, ads volume, campaigns, ad sets, ads, and creatives.
Create, update, and delete campaigns, ad sets, and ads; create single-text or dynamic asset-feed creatives; upload images/videos.
Pull insight metrics for campaigns, ad sets, or ads with date presets/ranges, breakdowns, filters, and pagination.
Run bulk pause/activate campaigns and bid updates through Meta's Batch API, with an ads-volume pre-flight for activations.
Manage Pages and auto-create/get a Page-Backed Instagram Account (PBIA) for Instagram placements.
Search Meta's public Ad Library for competitive research.
If a ScaleForge token is configured, README describes optional read-only tools for saved scans, scan comparison, watchlists, and hunted creatives (not included in the provided schema).
Control Facebook Ads from MCP-compatible agents using Meta Graph API v24.0. Provides tools for managing ad accounts, campaigns, ad sets, ads, creatives, and performance insights.
Control Instagram Ads from MCP-compatible agents using Meta Graph API v24.0. Provides tools for managing Instagram ad placements, Page-Backed Instagram Accounts (PBIA), and Instagram user IDs for ad creatives.
Control Facebook & Instagram Ads from MCP-compatible agents using Meta Graph API v24.0. Offers 32 tools for ad account management, bulk campaign operations, image and video asset uploads, and automated error handling for rate limits and token expiry.
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 reachedhalfway 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_specis gone entirely,asset_feed_idhas 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 Foundon 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.
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 orAuthorization: Bearer <token>header. A request with no token at all gets401with 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/mcpby 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 |
| ScaleForge | ScaleForge data tools (+ Meta Ads tools when a Meta token is sent) |
| 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):
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 withsf_.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-adsClaude 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 continueSmithery 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-adsVerify 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-adsThe 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-adsArchitecture
┌──────────────┐ 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)
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_managementads_readbusiness_managementpages_read_engagementpages_manage_adsread_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:
META_ACCESS_TOKEN=EAAB...your-token... npx -y @getscaleforge/mcp-meta-adsIf 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 |
|
250-ads-per-Page silent cap |
|
Token-expired errors |
|
Instagram placements without IG login |
|
v22 deprecations | Uses |
Image hash scoping | Documented on |
Tools reference
38 tools across 11 categories — 32 Meta Ads tools + 6 ScaleForge data tools.
Accounts (3)
Name | Purpose |
| List Ad Accounts accessible to the token |
| Detailed info for one account (status, spend cap, balance) |
| Per-Page running-ads count + limit + remaining slots (pre-flight check) |
Campaigns (5)
Name | Purpose |
| Paginated campaign list |
| Single campaign by ID |
| WRITE — create new campaign (defaults to PAUSED) |
| WRITE — update any mutable field |
| WRITE — hard delete |
Ad Sets (5)
Name | Purpose |
| List by ad_account_id OR campaign_id |
| Single ad set by ID |
| WRITE — create ad set under a campaign |
| WRITE — update targeting, bid, budget, status |
| WRITE — hard delete |
Ads (4)
Name | Purpose |
| List by ad_account_id, adset_id, or campaign_id |
| Single ad by ID (incl. creative + issues + preview link) |
| WRITE — update name, status, swap creative |
| WRITE — hard delete |
Creatives (4)
Name | Purpose |
| List all creatives in an ad account |
| Single creative by ID |
| WRITE — single-text creative via |
| WRITE — dynamic/multi-text creative via |
Media (2)
Name | Purpose |
| WRITE — upload video via remote URL (returns video_id) |
| WRITE — upload image via remote URL (returns image_hash, scoped to account) |
Insights (3)
Name | Purpose |
| Metrics at campaign level with breakdowns |
| Metrics at ad set level |
| Metrics at ad level (compare creatives) |
Bulk (3)
Name | Purpose |
| WRITE (BULK) — pause many campaigns via Batch API |
| WRITE (BULK) — activate many + pre-flight ads_volume check |
| WRITE (BULK) — update |
Pages (2)
Name | Purpose |
| Facebook Pages the token can manage |
| Get or auto-create a Page-Backed Instagram Account |
Ads Library (1)
Name | Purpose |
| Public Meta Ad Library search for competitive research |
ScaleForge data (6, read-only, needs SCALEFORGE_API_TOKEN)
Name | Purpose |
| Saved Ad Library scans (advertiser or keyword), newest first; |
| One scan with its ads, trimmed for context ( |
| New / gone / still-running ads vs the previous scan of the same query |
| Ads bookmarked with Hunter |
| Watched competitor Pages with last re-scan counts |
| Ads of one Watchlist item ( |
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
ABCDand 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
444and555. Run the ads_volume pre-flight first; if any Page is over 85%, abort and tell me which.""Bump the bid on ad sets
6001and6002to $4.50. Convert to cents for me.""Create a new campaign in
act_777called '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_TOKENenv 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 callhttps://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.
Links
ScaleForge (managed platform): getscaleforge.com
Meta Marketing API docs: developers.facebook.com/docs/marketing-apis
License
MIT — see LICENSE.
Available Tools
32 toolsactivate_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
Scored across 32 tools
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.
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.
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.
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
Related MCP Connectors
Meta Ads MCP server: run Facebook and Instagram campaigns, ad sets, ads and reports from AI.
Hosted Meta Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted MCP server for marketing agencies: connect Google Ads, GA4, Search Console, Meta, LinkedIn and more to Claude or ChatGPT. Pull reports and make changes via OAuth login, no setup.
Google Ads MCP server: run Search, Display, Demand Gen and PMax campaigns from AI.
Related MCP Servers
- AlicenseAqualityBmaintenanceA 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.351,368Business Source 1.1
- AlicenseNot gradedqualityDmaintenanceUnofficial MCP server implementation for Facebook Business API. Enables LLMs to manage ad campaigns and ads via natural language.27 PyPI2MIT
- AlicenseAqualityCmaintenanceA 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.3517MIT
- AlicenseNot gradedqualityBmaintenanceA 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