ElasticFlow
Meta Ads MCP
by Serkan Haşlak· v1.0.0otherView source

77 Meta Ads operations in Claude — self-hosted, your token, no third party in the loop.

Campaigns, ad sets, ads, audiences, Conversions API, automated rules — 77 tools across 24 modules, deployed on your own Railway or Docker host.

Tools available
Most: 2977 tools
Account scope
25 capUnlimited
Bulk ops
1-by-150/call
Install on ElasticFlowSee 18 things Claude can do

Who this is for

Demand Generation Managerprimary fit

Launch and optimize Meta campaigns in plain English — pause underperformers, scale winners, and pull spend reports without leaving Claude.

See skills for this role
Growth Marketer

Run audience and creative experiments at API speed — duplicate ad sets, vary targeting, and pull insights faster than Ads Manager allows.

See skills for this role
Marketing Lead

Get cross-account performance snapshots and budget pacing without waiting on your media buyer to compile reports.

See skills for this role
Product Marketer

Promote new launches across Facebook and Instagram from the same brief — campaigns, ad sets, creatives in one prompt.

See skills for this role

I have heard of a ton of instances where someone set up a Meta MCP with Facebook and got banned. Even my AM confirmed this happening.

— Eric Carlson — Paid Media Operator on X

How this changes your work

Daily account health check

Today

Open Ads Manager, click into each campaign, hit Columns → Performance, screenshot the table, paste into a Slack thread. 25 minutes — every morning.

With Meta Ads MCP
You ask

Show me yesterday's ROAS and spend for active campaigns across all my accounts, sorted by overspend.

Claude

Yesterday's account health

12 active campaigns across 3 accounts. 4 overspent vs. daily cap by >15%. Worst: ZestPro Q4 Sale — $312 over, ROAS dropped from 2.4 to 1.1.

Data fetched live from Meta Insights via get_insights + get_account_insights.

25 min → 30 sec

operator-reported time on a similar daily review flow

Pause underperformers, scale winners

Today

Ads Manager doesn't let you select 15 ad sets across 3 campaigns and pause in one click. You do it one by one, hoping you don't miss one.

With Meta Ads MCP
You ask

Pause every ad set where 7-day CPC is above $3 and frequency is over 4.

Claude

Bulk pause: 8 ad sets across 3 campaigns

8 ad sets matched the rule. Paused: AS_103, AS_119, AS_201, AS_204, AS_207, AS_312, AS_318, AS_341. Combined daily budget freed: $640.

Uses batch_request — up to 50 Graph API sub-requests per call.

1 prompt, 8 changes

batch API caps at 50 sub-requests

Launch a campaign from a brief

Today

You write the brief in Notion, open Ads Manager, create the campaign, then each ad set, then each ad, then upload or attach the IG creative. 45-60 min per launch.

With Meta Ads MCP
You ask

Launch a Spring Sale campaign: $50/day, target US 25-45 interested in shopping, use my @brand IG Reel from yesterday.

Claude

Campaign Spring Sale created

Campaign + 1 ad set + 1 ad live. Targeting: US, 25-45, Online Shopping interest. Creative: source_instagram_media_id 17841412345. Daily cap: $50.

Used create_campaign + create_adset + create_creative + create_ad in sequence.

45 min → 4 min

create_creative accepts source_instagram_media_id natively

Cross-account weekly report

Today

Pull insights for each of your 12 client accounts, copy to a Google Sheet, build the WoW comparison. 2 hours every Monday.

With Meta Ads MCP
You ask

Give me WoW spend, CPA, and ROAS for all client accounts. Flag any account where CPA grew >20% WoW.

Claude

Weekly client snapshot — 12 accounts

9 accounts steady. 3 flagged: Acme (CPA +34%), Helios (CPA +27%), Nymph (CPA +22%). Total spend $48,210 (-6% WoW). Avg ROAS 3.2.

batch_request fan-out across accounts; get_account_insights with date_preset=last_7d + last_14d.

2 hr → 90 sec

batch API + native pagination through all accounts

Works with

Meta Ads

8 skills connected

Proof

77

tools across 24 modules

README v1.0.0 — full Meta Marketing API surface

50

max sub-requests per batch API call

README — Batch Operations

200 ms

minimum delay between Meta API requests

README — BUC-based adaptive rate limiting

v28.0

Meta Graph API version (configurable)

README — Configuration Reference

30 min

session TTL — token cached per session

README — Enterprise-Ready

Use it with

Meta Ads MCP works with Claude Desktop, Claude Code, Cursor, Codex, Gemini, Windsurf, OpenClaw, and Hermes — any MCP-compatible AI client. Get it running in seconds.

Compatible withClaude Code (remote)Claude Desktop (local stdio)Dev mode (stdio with tsx)
Install on ElasticFlow
One click. Managed auth.

Pre-configured environment, OAuth handled for you. No command-line work.

Install on ElasticFlow →

Managed auth · No laptop setup.

Managed auth

Install on your AI client
Claude Code (remote) · Claude Desktop (local stdio) · Dev mode (stdio with tsx)

Copy a config snippet into your AI client and restart.

  • Set META_MCP_URL, MCP_API_KEY, META_ACCESS_TOKEN in your .env file — .mcp.json does the interpolation.
  • X-Meta-Token is passed per session — no shared workspace token.
{
  "mcpServers": {
    "meta-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "${META_MCP_URL}",
        "--header",
        "Authorization: Bearer ${MCP_API_KEY}",
        "--header",
        "X-Meta-Token: ${META_ACCESS_TOKEN}"
      ]
    }
  }
}

Recommended setup: meta-mcp runs on your own Railway or Docker host, Claude Code connects via mcp-remote.

Authentication

Steps

  1. Create a Meta Developer App

    Go to developers.facebook.com → My Apps → Create App. Pick the 'Business' app type. You'll need this app to mint a System User access token in the next step.

  2. Generate a System User access token

    Business Suite → Settings → Users → System Users. Create a System User, assign it to your ad account with Admin role, then generate a long-lived token. Grant ads_management and ads_read at minimum.

  3. Set environment variables

    In your .env file: META_ACCESS_TOKEN=<your system user token>, META_AD_ACCOUNT_ID=act_123456789 (fallback default), MCP_API_KEY=<strong random string> (gates the MCP server itself).

  4. Run locally or deploy to Railway

    Local: npm install && npm run build && npm start. Cloud: fork the repo, connect to Railway, paste the env vars, deploy. Server starts on http://localhost:3000 or your Railway URL — verify /health returns status:ok.

  5. Connect Claude with mcp-remote

    Paste the .mcp.json block from the install section. The X-Meta-Token header passes your Meta token per session — no shared workspace bot token, scoped per user.

Scopes explained

ScopeWhy this MCP needs it
ads_managementRequired — create, modify, and pause your campaigns, ad sets, and ads.
ads_readRequired — read campaign performance, insights, and account structure.
pages_read_engagementOptional — needed only when promoting existing Facebook Page posts as ads.
leads_retrievalOptional — needed only when pulling Lead Generation form submissions.

Troubleshooting

~7 min first time

OTHER · v1.0.0 · released today

What Claude can do

All 77 tools cover the full Meta Marketing API surface. These 18 are the ones daily Meta operators reach for first — grouped by job, not by API namespace.

Full CRUD across the campaign tree, plus time-based budget schedules.

Pull every campaign with status and budget

Filter by status, objective, or date range. Returns id, name, daily/lifetime budget, objective, bid strategy.

Launch a campaign from a one-line brief

Create with objective (OUTCOME_SALES, OUTCOME_TRAFFIC, etc.), budget, bid strategy, and special_ad_categories.

Duplicate a winner with all its settings

Clones campaign + ad sets + ads — A/B variants without rebuilding from scratch.

Show the 3 underlying tools

list_campaigns · create_campaign · copy_campaign

Common questions

Will this get my Meta ad account banned?

Self-hosted means you control the deployment — your Meta access token never touches a third-party SaaS. The bans operators report came from MCPs that proxy through shared infrastructure or that violate rate limits. meta-mcp runs on your Railway or Docker host with BUC-aware adaptive throttling (200 ms minimum delay; backs off at 75% utilization) and uses your own System User token. That's the same setup pattern as a directly-integrated internal tool — not flagged.

— Eric Carlson on X — 'ton of instances where someone got banned'
How does it handle ad accounts beyond the first 25?

Pass limit=100 to get_ad_accounts, or use the after cursor to walk every page. The 25-cap problem is documented in competing MCPs (brijr/meta-mcp#17 from a System User with 40+ accounts; brijr/meta-mcp#2 from someone with 100+). meta-mcp forwards pagination params directly to Graph API so you reach the long tail.

— Rafael de Sá — agency operator with 40+ accounts
Can I promote an existing Instagram Reel as an ad?

Yes — create_creative accepts source_instagram_media_id at the top level, the field Meta's Marketing API requires for promoting IG Reels/Feed/Stories. This is the workflow that breaks in MCPs that only accept object_story_id (Facebook page posts) and forces a fall-back to Ads Manager.

— Igor Andrade — Instagram-post-as-ad use case
Is this an official Meta product?

No. It's an open-source, ISC-licensed community implementation by Serkan Haşlak. Meta launched its own official Meta Ads MCP on April 29, 2026 with 29 tools. meta-mcp covers 77 tools across 24 modules — the longer tail of the Meta Marketing API: budget schedules, automated rules, custom conversions, batch API, lead-gen forms. Pick the official MCP for read-only basics; pick meta-mcp when you need the full surface.

What Meta API scopes does it need?

Required: ads_management (create/modify campaigns) and ads_read (pull insights). Optional: pages_read_engagement (promote existing Facebook Page posts as ads) and leads_retrieval (read Lead Gen form submissions). Generate a System User token with these scopes once and store it in your .env.

Does it handle the appsecret_proof requirement?

Yes — set APP_SECRET in your .env and the server signs each Graph API call with HMAC-SHA256(app_secret, access_token). This is required when your Meta App has 'Require App Secret Proof' enabled in App Settings → Advanced. Most production-ready Meta apps need it.

— Thomas Witt — appsecret_proof workaround on a competing MCP

What's new

  • vv1.0.014-05-2026

    Initial public release. 77 tools across 24 modules. Dual MCP/REST interface. BUC-based adaptive rate limiting. Docker + Railway deployment. Conversions API + Pixel + Lead Gen forms + budget schedules + automated rules.