Meta Ads Mcp

Meta Ads MCP Server

> Self-hosted Model Context Protocol (MCP) server that gives Claude, ChatGPT and other AI agents secure, multi-tenant access to the Meta Marketing API for Facebook Ads and Instagram Ads. Built for advertising agencies managing many client ad accounts from a single AI assistant — with OAuth login, encrypted-at-rest tokens, rate-limit compliance and circuit breakers baked in. > > v3.0.0 (2026-05-06) — vocabulary aligned with Meta's official MCP server (mcp.facebook.com/ads). Tool names switched from meta_ads_* to ads_*, added 14 new tools (insights views, diagnostics, help search, agency macros). Breaking change — see [CHANGELOG](CHANGELOG.md) and [docs/migration-v3.md](docs/migration-v3.md).

[](LICENSE) [](https://github.com/byadsco/meta-ads-mcp/actions/workflows/ci.yml) [](https://nodejs.org) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io) [](https://cloud.google.com/run)

Table of contents

• [What is Meta Ads MCP?](#what-is-meta-ads-mcp)
• [Who is this for?](#who-is-this-for)
• [Aligned with Meta's official MCP](#aligned-with-metas-official-mcp)
• [Features](#features)
• [Tools (135 total)](#tools-135-total)
• [Quick start](#quick-start)
• [Authentication — three modes](#authentication--three-modes)
• [Setting up Sign in with Meta](#setting-up-sign-in-with-meta)
• [Registering System User tokens (no expiry)](#registering-system-user-tokens-no-expiry)
• [Connecting AI clients](#connecting-ai-clients)
• [Common workflows](#common-workflows)
• [Architecture overview](#architecture-overview)
• [Meta API compliance](#meta-api-compliance)
• [Deployment](#deployment)
• [Local development](#local-development)
• [Security](#security)
• [FAQ / troubleshooting](#faq--troubleshooting)
• [Contributing](#contributing)
• [Resources](#resources)
• [License](#license)

What is Meta Ads MCP?

Meta Ads MCP Server is an open-source Model Context Protocol server that exposes the Meta Marketing API — the API behind Facebook Ads and Instagram Ads — as a set of well-typed tools that any MCP-compatible AI agent can call. Drop it in front of Claude, ChatGPT, Cline, Continue or any other MCP client and your assistant can manage campaigns, ad sets, creatives, audiences, insights, leads, comments and pixels across an unlimited number of ad accounts.

It is multi-tenant by design. Each user signs in with Facebook Login on a consent page, their long-lived (60-day) Meta token is encrypted with AES-256-GCM and stored in Firestore, and every MCP request automatically picks up the right token. There is no shared PIN, no token pasting, no plaintext at rest.

It is compliance-first. Every Meta throttling header (X-App-Usage, X-Business-Use-Case-Usage, x-fb-ads-insights-throttle, x-ad-account-usage, reach throttle) is parsed and respected per (token, account, use-case) bucket. A circuit breaker stops all calls for an account on abuse signal 1996 or repeated throttles. Insights guardrails reject dangerous parameter combinations before they hit Graph API.

It is deploy-ready. Stateless Streamable HTTP transport, Docker image, GitHub Actions workflow that ships to Google Cloud Run with Workload Identity Federation, gitleaks-scanned on every push, masked health checks. Or run it via stdio for single-tenant local use with Claude Desktop.

Who is this for?

• Marketing agencies that manage many client ad accounts and want one AI assistant that can act across all of them.
• In-house marketing teams with multiple users who need their own Meta token but a shared MCP endpoint.
• Developers building AI-powered tools, copilots or autonomous agents on top of Meta Ads.
• Solo operators who want to drive their own Meta account from Claude Desktop with zero infrastructure (stdio mode).

Aligned with Meta's official MCP

On 2026-04-29 Meta launched a first-party remote MCP server at mcp.facebook.com/ads (the "Ads AI Connectors" umbrella) with native support for ChatGPT, Claude, and Perplexity. v3.0.0 of this project aligns its vocabulary so the same prompts and agent patterns transfer cleanly between both servers.

| | Meta's official MCP (mcp.facebook.com/ads) | This project | |---|---|---| | Auth model | Per-user OAuth in your AI client | Multi-tenant: agency operator handles N client accounts from one server | | Tool surface | 29 tools (campaigns, ads, catalogs, 5 insight views, opportunity_score, dataset, errors, help) | 126 tools including the official 29-equivalent + audiences, lookalikes, lead forms, automated rules, A/B studies, async reports, billing invoices, custom conversions, asset uploads, comment moderation, cross-account macros, and full WhatsApp Business management (templates, phone numbers, flows, QR codes) | | Hosting | Hosted by Meta | Self-hosted on Cloud Run / your infra; tokens encrypted at rest in Firestore | | Cross-account | Per-user, single Meta login | Yes — ads_portfolio_summary aggregates across N accounts | | Token control | Lives in your AI client | Server-side System User token registry per agency operator | | Naming | ads_create_campaign, ads_update_entity, ads_insights_* | Same naming, plus all the tools the official MCP doesn't ship |

When to use which:

• Single advertiser running their own ads from Claude/ChatGPT → Meta's

official MCP. Zero setup, first-party.

• Agency operating across many client accounts, internal staff that should

not have direct Facebook login to every client, custom workflow / governance needs, integration with internal stack → this project.

Features

• 135 tools covering campaign management, creatives, targeting, audiences, reporting, comments, billing, invoices, tokens, Instagram workflows, WhatsApp Business management, rate-limit observability, semantic insight views, diagnostics, help-center search, competitor research via the public Meta Ad Library, and agency-tier cross-account macros.
• Aligned vocabulary with Meta's official MCP server so agents transfer cleanly between both.
• Sign in with Meta (Facebook Login) — replaces shared PINs. Each user lands their own long-lived (60-day) Meta token.
• System User token registry — for tokens that don't expire, register them per user from the consent UI.
• Encrypted persistence — Meta tokens stored AES-256-GCM in Firestore; survive restarts so connections never drop.
• Email / domain / FB-id allowlist — public repo, private deployment: only listed identities can sign in.
• Multi-account support — each request carries its own Meta access token via AsyncLocalStorage request context.
• Cloud-ready — Streamable HTTP transport, stateless, Docker-ready, Google Cloud Run reference deploy.
• Stdio support — for local development with MCP clients like Claude Desktop.
• Compliance-first rate limiting — per-(token, ad-account, use-case) bucketing of every throttle signal Meta publishes; reacts to estimated_time_to_regain_access instead of blind backoff.
• Circuit breaker — abuse-signal (subcode 1996), temporary-block and repeated-throttle events stop all calls for the affected account, following Meta's explicit "stop making API calls" rule.
• Preventive write pacing — Ads Management POST/DELETE are paced against the hourly BUC quota so bursts from agents never blow the limit.
• Insights guardrails — dangerous parameter combinations (account-level + high-cardinality breakdowns, lifetime + breakdowns in sync, time_range > 37 months) are rejected before hitting Meta.
• Async reports with safe polling — ads_run_report_and_wait one-shot with 5 s-min / 60 s-max backoff, proper Job Failed / Job Skipped handling.
• Retry logic — exponential backoff on truly transient errors only (never on throttled requests).

Tools (135 total)

Ads tools use the ads_* naming convention, aligned with Meta's official MCP server; WhatsApp Business tools use whatsapp_*. Read tools declare readOnlyHint: true; mutating tools declare destructiveHint / idempotentHint and prefix descriptions with a ⚠️ warning.

| Category | Tools | Description | |---|---|---| | Accounts | 3 | ads_get_ad_accounts, ads_get_account_info, ads_get_pages_for_business | | Campaigns | 5 | CRUD + status management | | Ad Sets | 6 | CRUD + clone bundle (native ad-copy, 100% creative-type coverage incl. dynamic/Advantage+) | | Ads | 6 | CRUD with creative assignment, UTM (url_tags) editing | | Creatives | 9 | List, details, create/update, image/video library and uploads | | Creative media | 1 | ads_get_creative_media — downloads an ad's images (incl. carousel cards and video thumbnails) and returns them as inline MCP image blocks for visual analysis; videos come with a signed source URL for external download | | Generic entity helpers | 3 | ads_get_ad_entities, ads_update_entity, ads_activate_entity (mirror official MCP) | | Insights — power tool | 1 | ads_get_insights — full control over breakdowns, attribution, time series | | Insights views | 5 | performance_trend, anomaly_signal, auction_ranking_benchmarks, industry_benchmark, advertiser_context | | Targeting | 7 | Interest / behavior / demographic / geo search, audience estimation, targeting description | | Budget | 1 | Budget schedule management | | Leads | 4 | Lead forms and lead retrieval | | Audiences | 8 | Custom audiences, lookalikes, and cross-account sharing | | Previews | 2 | Ad previews before launch | | Pixels | 5 | Pixel details, events, custom conversions | | Comments | 4 | Ad comment moderation | | Rules | 5 | Automated rules and rule details | | A/B Testing | 3 | Ad study creation and inspection | | Reports | 4 | Async report creation, status, retrieval, and one-shot run+wait | | Billing | 4 | Billing info, spend limits, and invoices (ads_get_invoices) | | Diagnostics | 3 | ads_get_opportunity_score, ads_get_dataset_quality, ads_get_errors | | Help search | 1 | ads_get_help_article — curated Meta Business Help Center search | | Agency macros | 2 | ads_diagnose_underperformance, ads_portfolio_summary (cross-account) | | Bulk ad creation | 1 | ads_bulk_create_video_ads — video URLs → upload, processing wait, auto-thumbnail, creative and ad in one call | | Instagram | 2 | IG account and media lookup | | Ad Library (Apify) | 8 | Competitor ad research: ads_library_scrape the public Meta Ad Library by keyword or Facebook page, poll run status, page through results, abort runs, plus per-user Apify token register/status/delete | | Tokens | 4 | List / set-active / register / delete | | Rate Status | 1 | Live view of quota usage, open circuits and write-pacer state | | WhatsApp — WABAs & phones | 8 | whatsapp_get_business_accounts, phone number list/register/deregister/verify, business profile get/update | | WhatsApp — Templates & analytics | 6 | Message template CRUD (whatsapp_create_template, edit, delete), WABA analytics (messaging/conversation/pricing), per-template analytics | | WhatsApp — Flows | 6 | Flow list/create/update (incl. Flow JSON upload), publish, deprecate, delete | | WhatsApp — QR & webhooks | 7 | QR deep-link CRUD (message_qrdls), webhook subscription get/subscribe/unsubscribe |

The ads_library_* tools read the public Meta Ad Library through the curious_coder/facebook-ads-library-scraper Apify actor, so they need no Meta permissions — but they do need an Apify token and they cost money (about $0.75 per 1,000 ads). Each user registers their own token with ads_library_register_apify_token; it is validated against the Apify API and then stored encrypted with AES-256-GCM in Firestore, scoped to that user, exactly like Meta tokens. Every scrape sends Apify a hard maxTotalChargeUsd cap derived from the requested count, so a single run cannot bill past it (the cap is per run, not a per-tenant budget).

Registering the token does not require going through an assistant: the server serves an authenticated /auth/connections page that lists your stored Meta tokens and your Apify connection, and lets you register, replace or disconnect the Apify token at any time. The consent screen shown during OAuth approval carries the same Apify section for first-time setup, plus a link to that page. The ads_library_register_apify_token tool still works for agents and headless setups.

Credential resolution fails closed: in multi-tenant mode a caller with no OAuth identity is refused rather than falling back to a shared credential. The APIFY_TOKEN environment variable is honoured only in single-tenant mode (stdio transport, or no Meta OAuth app configured), so one advertiser's scrapes can never be billed to the operator's Apify account.

Two operational caveats worth knowing: runs execute against the actor's latest build, so an upstream change to its input schema or pricing can alter behaviour without a change in this repo; and a scrape start that times out is indeterminate rather than failed — Apify may have accepted it — so check ads_library_list_runs before starting another.

WhatsApp tools require the whatsapp_business_management permission. Tokens issued before this scope was added must be re-authorized (sign in again through the OAuth flow) before the whatsapp_* tools will work, and the Meta App must have the WhatsApp product added in the developer dashboard.

Tool definitions live under [src/tools/](src/tools/), wired together in [src/tools/index.ts](src/tools/index.ts).

Quick start

Prerequisites

• Node.js 20.10+ (the project uses Import Attributes for JSON imports). Node 22 is used in the Docker image.
• A Meta access token with ads_management and ads_read permissions, or a Meta App configured for Facebook Login (see below).

Install & run

Option A — from source (contributors, self-hosters):

git clone https://github.com/byadsco/meta-ads-mcp.git
cd meta-ads-mcp
npm install
npm run build
npm start

Option B — from GitHub Packages (npm): scoped to @byadsco, hosted on npm.pkg.github.com. Requires a GitHub Personal Access Token with read:packages scope.

# tell npm where the @byadsco scope lives
echo "@byadsco:registry=https://npm.pkg.github.com" >> .npmrc
echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> .npmrc

npm install @byadsco/meta-ads-mcp
npx meta-ads-mcp                 # HTTP transport, port 3000
npx meta-ads-mcp --transport stdio

Option C — from GitHub Container Registry (Docker):

docker pull ghcr.io/byadsco/meta-ads-mcp:latest
docker run --rm -p 3000:3000 --env-file .env ghcr.io/byadsco/meta-ads-mcp:latest

The server starts on http://localhost:3000 with the /mcp endpoint and a health check at /health. New versions are published on every GitHub Release (releases).

Environment variables

See [.env.example](.env.example) for the full list. The minimum to run an HTTP deployment with Meta OAuth login:

SERVER_URL=https://your-host.com   # required for OAuth redirect URIs
META_APP_ID=...                    # your Meta app
META_APP_SECRET=...
AUTH_ALLOWED_EMAILS=you@x.com      # at least one allowlist source required
TOKEN_ENCRYPTION_KEY=$(openssl rand -hex 32)
SESSION_COOKIE_SECRET=$(openssl rand -base64 32)
OAUTH_SECRET=$(openssl rand -hex 32)
FIRESTORE_PROJECT_ID=my-gcp-project

For local development with stdio (no OAuth, no Firestore needed):

META_ACCESS_TOKEN=EAA...           # the only required value in stdio mode

Authentication — three modes

| Mode | Activated by | Used for | |---|---|---| | Sign in with Meta (recommended) | META_APP_ID + META_APP_SECRET + TOKEN_ENCRYPTION_KEY + allowlist | Each user signs in with Facebook Log

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: byadsco
• Source: byadsco/meta-ads-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.