Meta Ads MCP Server (Facebook & Instagram, 1-click connect)

Meta Ads MCP Server: run your Facebook & Instagram ads from Claude or ChatGPT

Paste one link into Claude or ChatGPT, sign in with Facebook, and your AI can read and manage your Facebook and Instagram ads. No developer account, nothing to install, about a minute of setup. Everything below the link is the full reference for you and your AI agent.

Your MCP link

https://connector.get-ryze.ai/mcp

Full setup guide ↓

Set it up in 3 stepsabout 1 minute

1. 01Copy your MCP link:https://connector.get-ryze.ai/mcp
2. 02In Claude go to Settings → Connectors → Add custom connector. Name it Ryze AI, paste the link, click Add. In ChatGPT it is Settings → Apps → Create app.
3. 03Click Connect, sign in with Facebook, pick your workspace. Open a new chat and ask: “Which of my ads wasted the most money this month?”

Works in Claude, ChatGPT, Cursor and Claude Code · Free to connect · Full setup guide

One URL between your AI client and Meta Ads

01 — Overview

What this Meta Ads MCP server does

The short version

1. One URL, https://connector.get-ryze.ai/mcp, works in Claude, ChatGPT, Claude Code, Cursor and any MCP client.
2. Sign in with Facebook. No Meta developer app, no access token, no app review, no server to run.
3. 12 Meta Ads tools: 9 read (Insights, Graph reads, creatives, leads, Ad Library) and 3 write, each approval-gated.
4. Same endpoint carries Google Ads, TikTok, GA4, Search Console and Shopify — 150+ tools in total.
5. Free to connect. Paid Ads Autopilot is $89/mo flat if you want Ryze AI to run the optimizations for you.

meta_ads · server specOAuth2

Server name

Ryze AI (Meta Ads MCP)

Endpoint

https://connector.get-ryze.ai/mcp

Transport

Remote MCP over Streamable HTTP

Auth

OAuth 2.0 (Facebook sign-in, one Ryze workspace per connection)

Hosting

Hosted by Ryze AI — nothing to install or run

Meta Ads tools

12 (9 read · 3 write, approval-gated)

Also on this endpoint

Google Ads, TikTok, GA4, Search Console, Shopify — 150+ tools

Developer app / token

Not required

Price

Free to connect · Paid Ads Autopilot $89/mo flat

Updated

September 3, 2026

MCP (Model Context Protocol) is the open standard AI assistants use to call external tools. A Meta Ads MCP server turns your Facebook and Instagram ad accounts into a set of those tools, so an assistant can diagnose a CPM spike, rank fatiguing creatives, export leads or shift a budget from a chat instead of Ads Manager. Most Meta Ads MCP servers on GitHub are local Python processes you configure with your own Meta app and access token; this one is hosted, so the whole setup is a URL and a Facebook sign-in. The comparison further down covers when self-hosting is the better route.

/01

Managed Facebook OAuth

Browser sign-in with Facebook, tokens exchanged and refreshed server-side. No Meta developer app, no Marketing API token, no app review.

/02

Raw Insights API

runRawInsights reports at account, campaign, ad set or ad level with breakdowns by age, gender, country, region, device, platform and placement, plus attribution windows.

/03

Full Graph API reads

runGraphRead fetches any node or edge — campaigns, ad sets, ads, creatives, audiences, targeting search — and follows pagination cursors.

/04

Approval-gated writes

Create and update campaigns, ad sets, ads, creatives and budgets through per-tool approval. Deletes and archives use a separate, explicit tool.

/05

Lead forms and leads

List the lead forms on a Facebook Page and export the leads a form collected, straight into the chat.

/06

Ad Library search

Search Meta's public Ad Library by keyword or Page ID, filtered by country and active status, with a snapshot link per ad.

/07

Creative tooling

Inspect any creative's copy, media and links, and upload images by URL to get the image_hash a new ad needs.

/08

Six platforms, one URL

The same endpoint carries Google Ads, TikTok, GA4, Search Console and Shopify toolsets — one login instead of six servers.

Six platforms, one endpoint

02 — Tool reference

The 12 Meta Ads tools

Account tools take adAccountId in the act_1234567890 form. Page-scoped reads and lead tools take pageId, and the server exchanges the Page access token Meta requires. Write tools are approval-gated.

Tool	Access	What it does	Key parameters
getAccountSummary	read	Spend, impressions, CPM, CTR, conversions and ROAS for a date range on Meta's default attribution window.	adAccountId · period { startDate, endDate }
listAdAccounts	read	Every Meta ad account the signed-in user can reach, with id (act_…), name and currency. Call this first.	none
getCreative	read	One creative by id: copy, media, links, object_story_spec and status.	creativeId
listCreatives	read	Creatives in an account, paged to avoid rate-limit flags on large accounts.	adAccountId · limit (default 100, max 1,000)
listLeadForms	read	Lead generation forms on a Facebook Page, with status and questions.	pageId
listLeads	read	Leads collected by a form. The server exchanges a Page access token from pageId.	formId · pageId
runRawInsights	read	Any Insights API query: level, date range, fields, breakdowns, filters, attribution windows and time increments.	adAccountId · request { level, timeRange, fields, breakdowns, filtering, actionAttributionWindows, timeIncrement, limit }
runGraphRead	read	GET any Graph API node or edge, including targeting search and Page-scoped reads. Follow paging.next until it is absent.	path · fields · adAccountId · pageId
runGraphWrite	write	POST to create or update campaigns, ad sets, ads, creatives, budgets, audiences and videos. Status ACTIVE/PAUSED lives here.	path · params · adAccountId · pageId
runGraphDelete	write	Delete or archive. Campaigns, ad sets and ads use POST with status DELETED or ARCHIVED; edges use HTTP DELETE. Explicit approved list only.	path · method (POST | DELETE) · params · adAccountId
searchAdLibrary	read	Public Ad Library search by keyword or Page IDs: creative bodies, titles, delivery dates, platforms, snapshot URL.	searchTerms | pageIds · countries · adActiveStatus · fields · limit (≤ 100) · after
uploadImageFromUrl	write	Fetch an image URL, upload it to act_<id>/adimages and return the image_hash for an ad creative.	adAccountId · imageUrl

The same endpoint exposes the Google Ads, TikTok, GA4, Search Console and Shopify toolsets. The cross-platform list lives in the advertising API & MCP tools reference; the Google side has its own page at Google Ads MCP server.

03 — Prerequisites

What you need before you start

You need

• A Facebook login with admin or advertiser access to the ad account, usually through Business Manager. (How to grant access.)
• A free Ryze AI account — created during the OAuth step if you don’t have one.
• An MCP client: Claude Pro, Team or Max (custom connectors are not on the free plan), ChatGPT Plus, Pro or Business with Developer mode, or Claude Code, Cursor, Windsurf, VS Code on any plan.

You don’t need

• A Meta developer app, app review, or a Marketing API access token. (What the API route involves.)
• A system user, a long-lived token to rotate, or the ads_management permission on your own app.
• Python, Node, a virtual environment, a .env file or a process to keep running.

04 — Setup

Install in every MCP client

All routes end in the same OAuth screen: sign in with Facebook, choose your Ryze workspace, click Allow. One connection maps to one workspace, so agencies with several client workspaces reconnect per workspace. Screenshots for the Claude route are in how to connect Claude to Google & Meta Ads.

Claude (web and desktop)

1. 01On claude.ai, click your avatar (bottom-left) → Settings.
2. 02Open the Connectors tab and click Customize, then the + next to Connectors.
3. 03Name: Ryze AI. Remote MCP server URL: https://connector.get-ryze.ai/mcp. Click Add.
4. 04Click Connect on the new connector, sign in with Facebook, pick your workspace and click Allow Claude to connect.
5. 05A green confirmation lists the available tools. Start a new chat and ask your first question.

Requires Claude Pro, Team or Max. The Claude desktop app uses the same Settings → Connectors flow; if you prefer the config file, use the mcp-remote entry under “Claude Desktop config file” below.

ChatGPT

1. 01 Settings → Apps. Under Advanced settings, turn on Developer mode.
2. 02Click Create app. Name: Ryze AI. MCP server URL: https://connector.get-ryze.ai/mcp — choose Server URL, not Tunnel.
3. 03Authentication: OAuth. Tick the acknowledgment and click Create.
4. 04On the authorization page choose Sign in with Ryze AI, pick your workspace and click Allow.
5. 05Start a new chat: “Pull the last 7 days of Meta spend and ROAS by campaign.”

Requires a ChatGPT plan that supports apps and connectors (Plus, Pro or Business).

Claude Code

claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp

Then run /mcp inside Claude Code to complete the OAuth sign-in. Add --scope user to make it available in every project.

Cursor, Windsurf and any mcp.json client

mcp.json (Cursor:.cursor/mcp.json · Windsurf: mcp_config.json)json

{
  "mcpServers": {
    "ryze": {
      "url": "https://connector.get-ryze.ai/mcp"
    }
  }
}

Save, then approve the OAuth prompt the client opens. Windsurf uses the key serverUrl instead of url.

VS Code (GitHub Copilot agent mode)

{
  "servers": {
    "ryze": {
      "type": "http",
      "url": "https://connector.get-ryze.ai/mcp"
    }
  }
}

Claude Desktop config file (optional)

{
  "mcpServers": {
    "ryze": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://connector.get-ryze.ai/mcp"]
    }
  }
}

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json. Restart Claude Desktop; the first call opens the browser for OAuth. Most people won’t need this — Settings → Connectors does the same without Node.

05 — Usage

What to ask once connected

Reporting

• >“Pull the last 7 days of Meta spend, CPM, CTR and ROAS by campaign.”
• >“Build my Monday Meta report: spend, ROAS, top 5 ads, and what to fix.”
• >“Break last month's spend down by placement — where is Instagram Reels vs Feed?”

CPM & creative fatigue

• >“Why did my CPM rise this week? Check frequency and CTR decay by ad set.”
• >“Which creatives are fatiguing? Rank ads by frequency and CTR trend over 4 weeks.”
• >“Compare Advantage+ shopping vs my manual campaigns on ROAS, last 30 days.”

Leads & competitors

• >“Export the leads from my 'Free audit' form this week and flag duplicates.”
• >“Show me the active ads Brand X is running in the US right now, with their hooks.”
• >“List every creative in the account that has been live for more than 60 days.”

Changes (approval-gated)

• >“Move 20% of budget from the two worst ad sets to the best one — show me the plan first.”
• >“Pause every ad with frequency over 4 and CTR under 0.8% this month.”
• >“Duplicate the winning ad into the retargeting ad set with the new image.”

Ready-made workflows: Meta budget optimization over MCP, placement optimization, Ad Library research from Claude, Pixel debugging and the media buyer’s guide to Claude.

06 — Request examples

Insights and Graph calls you can describe in the chat

You rarely need to write these — the assistant builds them. When you want exact control, describe the request and the server runs it through runRawInsights or runGraphRead. Three that come up daily:

Insights: campaign performance, last 30 days

{
  "level": "campaign",
  "timeRange": { "startDate": "2026-08-04", "endDate": "2026-09-02" },
  "fields": ["campaign_name", "spend", "impressions", "cpm", "ctr",
             "frequency", "actions", "purchase_roas"],
  "filtering": [{ "field": "spend", "operator": "GREATER_THAN", "value": 50 }],
  "limit": 50
}

Insights spend and action values arrive in whole currency units. purchase_roas is the ROAS field; there is no field called roas.

Insights: placement breakdown with a client's attribution window

{
  "level": "adset",
  "timeRange": { "startDate": "2026-08-27", "endDate": "2026-09-02" },
  "fields": ["adset_name", "spend", "cpm", "ctr", "actions"],
  "breakdowns": ["publisher_platform", "platform_position"],
  "actionAttributionWindows": ["7d_click", "1d_view"]
}

Each requested window arrives as an extra key on every action (e.g. '7d_click'); the plain value stays on the default window.

Graph read, then an approval-gated budget change

// runGraphRead
{ "path": "act_1234567890/adsets",
  "fields": "name,status,daily_budget,optimization_goal" }

// runGraphWrite  (approval-gated)
{ "path": "23851234567890123",
  "params": { "daily_budget": 5000 } }

Graph money fields are minor units: daily_budget 5000 = $50.00 (JPY and KRW are whole units). Updates need approval before they run.

07 — Compare

Hosted vs official vs self-hosted

What you operate	Ryze AI hosted server	Meta’s official MCP	Open source (e.g. GoMarble)
Runtime	None — remote HTTP	Local process you run	Local Python you run
Credentials you manage	Facebook sign-in only	Meta app + Marketing API access token	Meta app + access token in.env
Permissions & app review	Handled by Ryze	Your app's ads_read / ads_management scopes	Your app's scopes
Rate limits	Managed by Ryze's app	Your app's Ads Management limits	Your app's Ads Management limits
When the API version changes	Ryze updates the server	You update the server	You wait for a repo update
Platforms	Meta + Google Ads, TikTok, GA4, Search Console, Shopify	Meta only	Meta only
Write approval controls	Per-tool, on by default	Whatever your token allows	Varies by project

Self-hosting is the right call when the data must never leave your machine or you are building your own agent on top of the raw API. For that route: Meta’s official MCP explained, the Meta Business SDK MCP server, what the official MCP and CLI launch changed and the ranked best MCP servers for Meta Ads.

08 — Security & permissions

Safe by default

Reads run automatically, writes wait for you

OAuth 2.0 only

You sign in on Facebook's page. Your password never touches Ryze, and tokens are exchanged and refreshed server-side.

One workspace per connection

Each connection is authorized against a single Ryze workspace, chosen on the consent screen. Switching workspaces means reconnecting and starting a new chat.

Approval-gated writes

Read tools are automatic. In Claude, open Settings → Connectors → Ryze AI and keep runGraphWrite, runGraphDelete and uploadImageFromUrl on 'Needs approval' — the recommended default for live accounts.

Deletes are separate and explicit

Meta archives cascade — archive the last ad and the ad set follows — and cannot be undone, so runGraphDelete only runs on an item-by-item approved list. Pausing through runGraphWrite is the reversible path.

Revoke any time

Remove access from Facebook Settings → Business integrations, or from Workspace Settings → Integrations in Ryze.

09 — Quotas & limits

What to know before a heavy session

Developer app & token	Not yours to manage — the hosted server runs on Ryze AI's Meta app and permissions.
Rate limits	Meta's Ads Management limits apply per ad account and surface as error 80004. listCreatives pages at 100 by default (max 1,000); pull large accounts in pages.
Insights requests	Fields and breakdowns must be valid Insights names. Very wide date ranges can time out (error 100, subcode 1504018) — narrow the range or add timeIncrement.
Money fields	Insights spend and action values are whole currency units. Graph fields — daily_budget, lifetime_budget, bid_amount, amount_spent, spend_cap — are minor units: 5000 = $50.00 (JPY and KRW are whole units).
Attribution	Defaults to each ad set's own attribution setting, like Ads Manager. Pass actionAttributionWindows (1d_click, 7d_click, 28d_click, 1d_view) to mirror a client's window and read that key.
Pagination	A Graph read with paging.next is incomplete. Pass the whole paging.next URL as the next path until it is absent.
Leads	listLeadForms and listLeads need the Page ID; the server exchanges a Page access token. Requires the leads_retrieval and pages_read_engagement scopes on the connection.
Ad Library	Public archive, up to 100 ads per page and 10 countries per query. No spend or performance metrics except political and EU ads.
Media	Images upload from a URL via uploadImageFromUrl and return an image_hash. Videos post to act_<id>/advideos with a file_url and process asynchronously — poll status before building the creative.
Client plans	Claude custom connectors: Pro, Team or Max. ChatGPT connectors: Plus, Pro or Business with Developer mode.

10 — Troubleshooting

Common errors and the fix

Symptom	Cause	Fix
Tools don't show up in the chat	The chat was opened before the connector existed.	Start a new chat — Claude and ChatGPT bind connectors when a conversation starts.
No 'custom connector' option in Claude	Free Claude plan.	Custom connectors need Claude Pro, Team or Max. ChatGPT needs Plus, Pro or Business with Developer mode on.
"adAccountId is required" or the wrong account	No account chosen yet.	Ask for your ad accounts first (listAdAccounts) and name one. IDs look like act_1234567890.
Error 80004: too many calls to this ad account	Meta's Ads Management rate limit for that account.	Wait, then page through with smaller limits — pulling thousands of creatives in one call trips the flag.
Error 190 on a leads call	Lead retrieval needs a Page access token, or the leads_retrieval scope is missing.	Pass pageId (the Page that owns the form). If it persists, reconnect Meta and grant the leads permissions.
Error 100: invalid parameter on Insights	The field or breakdown is not an Insights field.	status, placement and creative are object attributes (use runGraphRead); roas is purchase_roas.
Numbers don't match Ads Manager	Different attribution window, or ad-level vs account-level conversions.	Pass actionAttributionWindows to mirror the client's window and read that key. Account rows include modeled conversions that ad rows do not.
Budgets look 100× off	Graph money fields are minor units.	daily_budget 5000 = $50.00; amount_spent '25468' = $254.68. Insights spend is already whole units.
"Ad Sets may not be added to archived Campaigns"	Archive cascade: archiving the last child archived the parent.	Read effective_status before deleting the last active child. Pause with runGraphWrite instead of archiving; update creatives in place.
Data from the wrong client account	The connection is authorized to another workspace.	Each connection is one Ryze workspace. Reconnect, pick the right workspace, and start a new chat.

Still stuck? Email support@get-ryze.ai. More Meta-side fixes: troubleshooting the Meta Ads MCP connection. Agencies juggling many accounts: MCP config for multiple ad accounts.

11 — FAQ

Meta Ads MCP server questions

What is the Meta Ads MCP server?

It is an MCP (Model Context Protocol) server that exposes a Meta ad account — Facebook and Instagram campaigns — as tools an AI assistant can call. Ryze AI's Meta Ads MCP server is hosted and remote: you add one URL to Claude, ChatGPT, Cursor or Claude Code, sign in with Facebook via OAuth, and the assistant can run Insights reports, read any Graph API object, search the Ad Library and make approval-gated changes.

What is the Meta Ads MCP server URL?

The server URL is https://connector.get-ryze.ai/mcp. It is a remote MCP server over Streamable HTTP with OAuth 2.0. The same endpoint serves the Meta Ads, Google Ads, TikTok, GA4, Search Console and Shopify toolsets, so one connector covers the whole ad stack. Each connection is authorized against one Ryze workspace.

Do I need a Meta developer app or a Marketing API access token?

No. The hosted server runs on Ryze AI's own Meta app and permissions. You sign in with a Facebook account that has admin or advertiser access to the ad account and you are done. Self-hosted servers such as Meta's official MCP or the open-source GoMarble server require your own Meta app, a long-lived access token and a local Python runtime.

Which MCP clients work with the Meta Ads MCP server?

Any client that supports remote MCP over HTTP with OAuth: Claude web and desktop (Pro, Team or Max plan), ChatGPT (Plus, Pro or Business with Developer mode), Claude Code, Cursor, Windsurf, VS Code and Gemini CLI, plus agent frameworks such as the Claude Agent SDK, OpenAI Agents SDK, LangChain, CrewAI and n8n.

How many Meta Ads tools does the server expose?

12 Meta Ads tools: 9 read tools (account summary, ad accounts, creative detail, creative list, lead forms, leads, raw Insights, raw Graph reads and Ad Library search) and 3 write tools (Graph writes, Graph deletes and image upload), each approval-gated. The full endpoint carries 150+ tools across six platforms.

Can the MCP server change my Facebook campaigns, or only read them?

Both. Read tools work the moment OAuth completes. runGraphWrite creates and updates campaigns, ad sets, ads, creatives and budgets, and is approval-gated: in Claude you set it to 'Needs approval' under Settings → Connectors → Ryze AI. Deletes and archives live in a separate tool, runGraphDelete, because Meta archives cascade and cannot be undone; it only runs on an explicit item-by-item list.

How do I run an Insights query through the MCP server?

Ask in plain English or describe the exact request. runRawInsights takes a level (account, campaign, adset or ad), a date range, any valid Insights fields, breakdowns such as age, gender, country, publisher_platform or platform_position, filters and attribution windows. Spend comes back in whole currency units, while Graph budget fields are in minor units.

Why don't the numbers match my Ads Manager?

Almost always the attribution window. By default the server follows each ad set's own attribution setting, like Ads Manager does, but a client may view a different window. Pass actionAttributionWindows such as ['7d_click','1d_view'] and read the value under that window key. Account-level conversions also include modeled conversions that ad-level rows do not, so ad-level sums run a few percent lower.

Can I export leads from lead forms with the MCP server?

Yes. listLeadForms returns the forms on a Facebook Page, and listLeads exports the leads collected by a form. Both need the Page ID, because Meta requires a Page access token for lead retrieval; the server exchanges it automatically. If you see Graph error 190 on a leads call, the connection lacks the leads_retrieval scope — reconnect Meta and grant it.

Does the Meta Ads MCP server include Ad Library competitor research?

Yes. searchAdLibrary queries Meta's public Ad Library by keyword or exact Page ID, filtered by country and active status, and returns creative bodies, link titles, delivery dates, platforms and a snapshot URL per ad. It uses a platform-level credential, so it is not limited to your own accounts. Spend and performance are not exposed except for political and EU ads.

What does the Meta Ads MCP server cost?

Connecting is free — a Ryze AI account costs nothing to create and the connector has no per-call fee. Paid Ads Autopilot is $89/month flat with a 7-day free trial if you want Ryze AI to run the optimizations for you. On the client side you need a Claude plan that allows custom connectors (Pro, Team or Max) or a ChatGPT plan with connectors (Plus, Pro or Business).

Is the Meta Ads MCP server secure?

Access is OAuth 2.0 only, so your Facebook password never touches Ryze. Each connection is scoped to one Ryze workspace, write and delete tools are approval-gated by default, and you can revoke access at any time from Facebook Settings → Business integrations or from Workspace Settings → Integrations in Ryze. The MCP privacy policy, MCP terms and security policy are linked on this page.

Why doesn't Claude see the Meta Ads tools after I connected?

Start a new chat. Claude and ChatGPT bind connectors when a conversation starts, so an existing chat keeps its original tool set. If the connector option is missing entirely, you are on a free Claude plan — custom connectors require Pro, Team or Max. Finally, confirm the connector shows Connected under Settings → Connectors.

How is this different from Meta's official MCP server?

Meta's official MCP is built for developers: you create a Meta app, manage Marketing API access tokens and permissions, run the server yourself and get Meta only. The Ryze AI server is hosted, needs nothing beyond a Facebook sign-in, adds Google Ads, TikTok, GA4, Search Console and Shopify on the same endpoint, and ships approval controls for every write.

12 — Compatibility

Works in every MCP client

Claude (web & desktop)01

Claude Code02

Claude Agent SDK03

ChatGPT04

OpenAI Agents SDK05

Cursor06

Windsurf07

VS Code08

Gemini CLI09

LangChain10

CrewAI11

n8n12

13 — Related

Keep reading

• Google Ads MCP server
• Meta's official MCP and CLI: what changed
• Connect Claude to Google & Meta Ads (screenshots)
• Best MCP for Meta Ads — servers ranked
• Best Claude connector for Meta Ads
• Meta Conversions API with Claude MCP
• MCP tools for ad campaign reporting
• Will connecting AI to your ads account get you banned?

One OAuth login · 12 Meta Ads tools · Live in ~60 seconds

Add Meta Ads to your AI today.

Free to connect. Upgrade to Paid Ads Autopilot ($89/mo flat, 7-day free trial) when you want Ryze AI to run the optimizations for you, 24/7.

2,000+ clients · 700+ agencies · $500M+ managed · No developer app · No server to run