Meta Ads MCP: Complete Setup Guide (2026)

TL;DR + what you actually need

Three things cover 90% of Meta Ads MCP setups:

• One URL: https://meta-ads.mcp.pipeboard.co/ — the hosted remote endpoint (streamable-http, the MCP transport for remote servers). No local install, no Python environment, no token files.
• One token: a Pipeboard API token from pipeboard.co/api-tokens, appended as ?token=YOUR_PIPEBOARD_TOKEN. Clients with interactive OAuth (Claude, Cursor) can skip the token and click “Connect” instead.
• Zero Meta credentials: you sign in to your Facebook Ads account once, at pipeboard.co. No Meta Developer App, no App Review, no Marketing API token to copy or rotate.

Quick installs, if you only came for the copy-paste:

• Claude (web/desktop): Settings → Connectors → add https://meta-ads.mcp.pipeboard.co/, then sign in when prompted.
• Claude Code: claude mcp add --transport http meta-ads "https://meta-ads.mcp.pipeboard.co/?token=YOUR_PIPEBOARD_TOKEN"
• Cursor: paste the JSON from the install card below into ~/.cursor/mcp.json.

One orientation note before anything else: “Meta Ads MCP” now names two different things. This guide covers the community server that started it all — Pipeboard’s meta-ads-mcp, the /servers/meta-ads catalog entry. Meta’s own official Ads connector (mcp.facebook.com/ads, launched April 2026) is a separate product with a separate auth model; we dissected it in our official Meta Ads MCP and CLI deep-dive. The two coexist, and the Alternatives section below tells you when to pick which.

What the Meta Ads MCP actually does

Meta Ads MCP is a server that exposes Meta’s Marketing API — the REST API behind Ads Manager — as MCP tools an agent can call. Your agent asks get_insights for last week’s performance and the server fires the corresponding Marketing API request against your ad account, parses the response, and hands back structured data the model can reason over. Same pattern for writes: create_campaign becomes a POST to the campaign endpoint, created in PAUSED status so nothing spends money without a human flipping it live.

What that buys you in practice: instead of exporting CSVs from Ads Manager into a spreadsheet, you ask “which ad sets had a CPA above $40 last week, and how does that compare to the week before?” and get an answer grounded in your actual account data — not a hallucinated estimate. The write tools close the loop: the same conversation that found the underperformer can draft the replacement ad set, paused, ready for your review.

The implementation this guide covers is github.com/pipeboard-co/meta-ads-mcp — a Python server by Pipeboard, shipped both as a hosted remote MCP and a PyPI package for self-hosting. It launched in mid-2025, well before Meta shipped anything official, and it remains the most-installed community option. One licensing footnote worth knowing: the project moved to the Business Source License (source-available, converting to Apache 2.0 in 2029), so “open source” in older coverage is now more precisely “source-available.”

Here is Pipeboard’s launch announcement, back when a Meta Ads MCP was a genuinely new idea:

The server does no media buying itself. It holds no opinions about your CBO settings, caches nothing, and adds no optimization layer — it is a thin adapter between agent and Marketing API. Two consequences. First, everything Meta enforces (ad-account roles, API rate limits, spend permissions) applies unchanged through MCP. Second, the quality of the analysis is the model’s, not the server’s — the same insights data that makes Claude useful here would make a bad prompt produce confident nonsense. The recipes below are tuned accordingly.

Auth model: three paths, ranked

Auth is where Meta integrations historically went to die — Developer Apps, App Review queues, tokens that expire mid-quarter. The Meta Ads MCP ecosystem in 2026 gives you three paths, and the right one is almost never the one Meta’s developer docs describe first.

Path 1 — Pipeboard token (recommended)

You create a free Pipeboard account, click Connect, and complete one Facebook OAuth login. Pipeboard stores that Meta grant in its cloud and issues you a Pipeboard API token at pipeboard.co/api-tokens. From then on, the only credential your MCP client ever sees is that token, passed in the server URL:

https://meta-ads.mcp.pipeboard.co/?token=YOUR_PIPEBOARD_TOKEN

Clients with interactive OAuth support (Claude’s Connectors UI, Cursor) can drop the token entirely — add the bare URL and a browser window handles login. The trade you are making is explicit: Pipeboard becomes a token broker holding a grant to your ad accounts. For a freelancer or in-house team that is usually fine; for a compliance-bound enterprise it may not be, which is what Path 2 is for. One token also unlocks Pipeboard’s sibling servers (Google, TikTok, Snap, Reddit Ads) — relevant if you read our three-platform ads MCP comparison and want one auth story across all of them.

Path 2 — bring your own Meta app (self-hosted)

The PyPI package (pip install meta-ads-mcp) can run against your own Meta Developer App instead of Pipeboard’s. That means touching the raw Marketing API auth model, so know what you are signing up for:

• Permissions: ads_read for insights and reporting, ads_management for writes, business_management if you manage Business-level assets. These are OAuth permission names, granted per app per user.
• Access tiers: a new app gets Standard Access, which covers ad accounts your own developer role already reaches. Managing arbitrary client accounts in production requires Advanced Access — App Review plus Business Verification, a process measured in days-to-weeks, not minutes.
• Token lifetimes: user access tokens are short-lived by default; the long-lived exchange gets you roughly 60 days before manual renewal. For always-on automation Meta’s answer is a System User token — a token attached to a non-human Business Manager identity, built for server-to-server use.

The repo itself is blunt about this path: the README points local installers at a separate streamable-http setup doc and states it “strongly recommend[s] using Remote MCP instead.” Our take matches: self-host only if a third-party token broker is a hard no for your org, and budget a day for Meta app plumbing when you do.

Path 3 — Meta’s official connector

Since April 2026, Meta’s own Ads MCP at mcp.facebook.com/ads uses standard Business OAuth — no Developer App, no token handling at all. The catch is availability: it is being gradually rolled out per ad account, and accounts outside the rollout get a hard “not enabled” error with no self-serve fix. Full auth walkthrough, tool list, and CLI coverage in the official connector deep-dive. If that rollout has reached your account, Path 3 is the least-friction option for Meta-only work — and the reason Paths 1 and 2 still exist is everyone it hasn’t reached, plus everyone who needs multi-platform or multi-client setups.

Install (every client)

The Pipeboard server is remote-first: every client points at the same streamable-http endpoint, so install is config-only — no subprocess, no Node or Python on your machine. The install panel below pulls its configs from the canonical /servers/meta-ads catalog entry. Tap your client’s row, copy, paste, restart.

One-line install · Meta Ads

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Client-specific notes the panel can’t hold:

• Claude (web / desktop, Pro or Max): Settings → Connectors → Add custom connector, name it Meta Ads, URL https://meta-ads.mcp.pipeboard.co/. Claude triggers the Pipeboard OAuth flow in a browser tab; sign in with the Facebook account that has access to your ad accounts.
• Cursor: add to ~/.cursor/mcp.json:

  {
    "mcpServers": {
      "meta-ads": {
        "url": "https://meta-ads.mcp.pipeboard.co/?token=YOUR_PIPEBOARD_TOKEN"
      }
    }
  }

  Drop the ?token= query to use interactive login instead. Config-file details at /clients/cursor.
• Codex CLI: Codex registers stdio servers in ~/.codex/config.toml; for a remote endpoint, bridge it with mcp-remote:

  [mcp_servers.meta_ads]
  command = "npx"
  args = ["-y", "mcp-remote", "https://meta-ads.mcp.pipeboard.co/?token=YOUR_PIPEBOARD_TOKEN"]

• Self-hosted (advanced): pip install meta-ads-mcp from PyPI, then follow the repo’s streamable-http setup doc to run it against your own Meta app (Path 2 above). Skip this unless you have the compliance reason.

Claude Code (the path we use)

One command, user scope, done:

claude mcp add --transport http meta-ads \
  "https://meta-ads.mcp.pipeboard.co/?token=YOUR_PIPEBOARD_TOKEN"

Run claude mcp list to confirm meta-ads registered, then start a session and ask for your ad accounts — the first tool call proves the token works. Because the token rides in the URL, avoid --scope project in shared repos: a committed .mcp.json with a live Pipeboard token is a leaked grant to your ad accounts. Keep it at user scope, or use the token-less URL with OAuth. Full flag reference at /clients/claude-code; every other client’s config path is at mcp.directory/clients.

Tools walkthrough

The README documents the tool surface in seven groups, every name prefixed mcp_meta_ads_ (shortened below). The shape mirrors the Marketing API’s object hierarchy — account → campaign → ad set → ad → creative — which is also the mental model the agent needs to navigate your account.

Accounts

get_ad_accounts, get_account_info, and get_account_pages. Every session starts here: ad account IDs (act_…) are the argument every other tool needs, and the agent will call get_ad_accounts first to find them. If this call returns an empty list, stop — your auth is fine but your Facebook user has no role on any ad account, and nothing else will work.

Campaigns

get_campaigns, get_campaign_details, and create_campaign. The create tool builds a campaign in PAUSED status with your chosen objective and budget mode — the agent drafts, you launch from Ads Manager after review.

Ad sets

get_adsets, get_adset_details, create_adset, and update_adset. This is where targeting lives — audiences, placements, optimization goal, frequency caps. update_adset is the most consequential write tool in the set: it can change budgets and bids on a live ad set, which is why confirmation-gated writes matter (see Limits).

Ads & creatives

get_ads, get_ad_details, create_ad, update_ad, get_ad_creatives, create_ad_creative, update_ad_creative, upload_ad_image, and get_ad_image. The sleeper here is get_ad_image — it pulls the actual creative image so a multimodal model can look at what you’re running, not just its metadata. That turns “why is this ad fatiguing?” from a numbers question into a numbers-plus-creative question, which is where the interesting answers are.

Targeting research

search_interests, get_interest_suggestions, validate_interests, search_behaviors, search_demographics, and search_geo_locations. These wrap Meta’s targeting search endpoints — the same autocomplete you get in Ads Manager’s audience builder, but queryable in bulk. The validate tool matters more than it looks: interest names the model “remembers” from training data frequently don’t exist as targetable entities, and validating before create_adset is the difference between a working draft and a silent failure.

Insights

get_insights — the single most-called tool, and the reason most people install this server. It wraps the Marketing API insights endpoint: spend, impressions, clicks, CTR, CPC, CPA, conversions, ROAS, broken down by date range and object level (account, campaign, ad set, or ad). Every analysis recipe below is some arrangement of get_insights calls plus in-context math.

Budget & auth helpers

create_budget_schedule schedules budget changes — the building block for “raise budget 20% for the weekend, revert Monday” without a 3 a.m. calendar reminder. get_login_link generates a fresh auth link when a connected account needs re-linking, and the generic search tool does cross-resource lookups when the agent doesn’t know which object type it’s hunting for.

Recipes

Six workflows where the server earns its slot in your client. All assume the remote server is registered with a valid token and your Facebook user has at least Advertiser role on the target ad account.

Recipe 1 — The Monday morning campaign review

Prompt: “Pull insights for all active campaigns, last 7 days vs the 7 days before. Flag anything where CPA moved more than 20% in either direction, and rank by spend. Three bullets per flagged campaign.” The agent calls get_campaigns once, get_insights twice (one per window), and does the diff in-context. This replaces the spreadsheet ritual that opens most media buyers’ weeks — and unlike the spreadsheet, you can immediately ask why a number moved.

Recipe 2 — Creative fatigue testing

Prompt: “For ad set X, get every ad’s insights by week over the last 4 weeks. Identify ads with declining CTR and rising frequency, then pull their creatives with get_ad_image and describe what the fatiguing ads have in common visually.” This is the workflow no dashboard does: joining the fatigue numbers to the actual pixels. The output — “the three declining ads all use the white studio background; the two holdouts are UGC-style” — is a creative brief, not a chart.

Recipe 3 — Budget audit across the account

Prompt: “List every active ad set with its daily budget and last-14-day CPA. Show me where budget concentration doesn’t match performance — high-budget/high-CPA and low-budget/low-CPA outliers — and propose a reallocation that keeps total spend flat.” The agent assembles the table from get_adsets + get_insights and proposes the moves. Have it draft the update_adset calls but approve each one yourself — budget moves are the one write class we never auto-confirm.

Recipe 4 — Audience research before a launch

Prompt: “We’re launching a sleep supplement. Use search_interests and get_interest_suggestions to map the targetable interest space around sleep, wellness, and adjacent behaviors. Validate everything, then propose three distinct audience definitions with no overlap in anchor interests.” Twenty minutes of Ads Manager autocomplete archaeology becomes one tool-call loop, and the validation step means every interest in the output actually exists.

Recipe 5 — Draft a full campaign, paused

Prompt: “Create a paused conversions campaign called ‘Q3-prospecting-test’, $50/day, one ad set per audience from Recipe 4, using the best-performing creative from our current prospecting campaign as the starting ad.” The agent chains create_campaign → create_adset → create_ad_creative → create_ad, confirming each write. You review the structure in Ads Manager and flip it live. The paused-by-default behavior is what makes this recipe safe enough to actually use.

Recipe 6 — Weekend budget schedule

Prompt: “Our weekend ROAS is consistently higher. Create a budget schedule that raises the prospecting ad set budget 25% Friday 6 p.m. through Sunday midnight, recurring.” One create_budget_schedule call encodes what would otherwise be a manual ritual someone forgets twice a month. Verify the first occurrence fired — scheduled writes are exactly where silent failures hide.

Limits + safety

Marketing API rate limits

Every tool call lands on Meta’s Marketing API, which rate-limits per ad account using a usage-based model — heavy bursts of calls earn cooldown windows, and limits tighten further for apps on lower access tiers. In MCP terms: an agent that loops get_insights per-ad across a 200-ad account can rate-limit the whole account, including for other tools your team runs against it. Tell the agent to batch — one account-level insights call with breakdowns beats fifty ad-level calls — and keep date ranges as tight as the question allows.

The hosted-dependency trade

The recommended path routes your traffic through Pipeboard’s cloud, which holds the OAuth grant to your ad accounts. That is a real trust decision, not a footnote: a comparison post at claudefa.st put the contrarian case plainly — now that Meta’s official MCP is free, a third-party broker needs a concrete reason to be in your stack (multi-platform coverage, client isolation, or self-hosting are the legitimate ones). If none of those apply to you and the official rollout has reached your account, take the official path.

Write safety

Three guardrails, layered: campaigns are created paused; write tools go through explicit confirmation prompts; and your Facebook user’s ad-account role caps what any of it can touch. A user with Analyst role makes the whole server read-only, which is a perfectly good way to run it — one r/FacebookAds commenter’s warning about agent-driven ads applies to every server in this category: “[it] won’t get u banned. but it can spend ur budget wrong.” Read-heavy, write-rarely, approve-always is the posture that earns the automation.

What the model gets wrong

Two recurring failure shapes. The model invents interest names that don’t exist as targetable entities — always route audience work through validate_interests. And it will cheerfully compare attribution-incompatible numbers (7-day click vs 1-day view) if your prompt doesn’t pin the attribution window. Neither is a server bug; both are why the recipes above specify windows and validation explicitly.

Troubleshooting

Official vs community: when to pick which

The honest 2026 decision tree, now that Meta competes with the community it inspired:

• Meta-only, account already in the rollout: use Meta’s official connector. First-party, free, OAuth-only, and the Meta-blessed answer to “will this flag my account?”
• Rollout hasn’t reached you, or you manage many client accounts: this guide’s Pipeboard server. No rollout gate, token-based auth you can script per client, and a self-hosting escape hatch the official surface doesn’t offer.
• Cross-platform media buying: Pipeboard’s family covers Google Ads, TikTok, Snap, and Reddit under the same token — one auth story for the whole stack. Our Meta vs Google vs TikTok Ads MCP comparison covers the per-platform trade-offs.
• Paid social is one input to a wider organic picture: pair an ads server with the search-and-analytics stack from our best SEO MCP servers guide — the paid/organic join (“did the ranking drop cause the CPA spike?”) is where agent-side analysis beats any single dashboard.

FAQ

Sources

• Primary repo: github.com/pipeboard-co/meta-ads-mcp (README: auth paths, tool list, client setup)
• PyPI package + license record: pypi.org/project/meta-ads-mcp
• First-party launch post: @PipeboardAI, July 10, 2025
• Meta Marketing API authorization docs: developers.facebook.com — Marketing API authorization
• Community: r/FacebookAds — “Meta just released Ads MCP” (rollout gating, budget-safety caution)
• Community: r/ClaudeAI — Meta Ads MCP permission-error thread
• Contrarian comparison: claudefa.st — official vs Pipeboard vs others
• Canonical MCP.Directory entry: /servers/meta-ads
• Official connector deep-dive: /blog/meta-ads-cli-mcp