Which integrations are available for this server?

Provides tools to query and manage Facebook ad accounts, campaigns, ad sets, ads, creatives, audiences, pixels, and performance insights through the Meta Ads API. Enables access to Instagram ad account data, including campaigns, ad sets, ads, and performance insights, via the Meta Ads platform. Offers integration with Meta Ads to list ad accounts, retrieve campaign and ad set details, pull performance metrics, estimate audience reach, search targeting options, and manage pixels and custom audiences.

meta-ads-mcp

by dhawalshah

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Facebook / Meta Ads MCP

A Model Context Protocol (MCP) server for Meta Ads. Connect Claude (or any MCP-compatible AI client) directly to your Facebook and Instagram ad accounts to query performance, analyse audiences, research competitors, and more — all in natural language.

What you can do

Account & Campaign Management

List all ad accounts linked to your token
Get detailed account info — spend, balance, currency, status
Browse campaigns, ad sets, and ads with filtering and pagination
Inspect individual campaigns, ad sets, ads, and creatives

Performance & Insights

Pull performance metrics at account, campaign, ad set, and ad level
Break down results by age, gender, country, device, placement, and more
Set custom date ranges or use presets (last 7d, last 30d, last quarter, etc.)
Use attribution windows: 1-day click, 7-day click, 1-day view, and more

Audiences

List custom audiences (CRM uploads, pixel-based, engagement-based, lookalikes)
View saved audience definitions and their estimated sizes
Estimate audience reach before launching a campaign
Get projected delivery metrics for an existing ad set
Get a plain-English description of any ad set's targeting

Targeting Research

Search available interests, behaviours, and demographics by keyword
Get targeting suggestions based on an existing audience spec

Pixels & Conversions

List Meta Pixels on the account
List custom conversion events being tracked

Creative Library

Browse the image library for an ad account
Preview how any ad renders across Facebook, Instagram, Stories, Reels, and more

Automation & Organisation

List automated ad rules (auto-pause, budget adjustment rules)
Review the execution history of any ad rule
List ad labels used to organise campaigns and ads

Lead Generation

Fetch lead form submissions for any Lead Gen ad

Prerequisites

Python 3.10+
A Meta access token with the following permissions:
- ads_read — required for all ad account tools
- pages_show_list + pages_read_engagement — required for Page tools
Dependencies listed in requirements.txt

Step 1: Get a Meta Access Token

Go to the Meta Developer Portal and create an app (or use an existing one)
Under your app, go to Tools → Graph API Explorer
Select your app, then click Generate Access Token
Add the permissions: ads_read, pages_show_list, pages_read_engagement
Copy the generated token

For long-lived tokens, exchange your short-lived token using the token exchange endpoint. Short-lived tokens expire in ~1 hour; long-lived tokens last ~60 days.

Step 2: Local Setup

git clone https://github.com/your-username/facebook-ads-mcp-server
cd facebook-ads-mcp-server

# Create and activate a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Step 3: Connect to Claude

Option A: Local (Claude Desktop — single user)

Add to your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "facebook-ads": {
      "command": "python",
      "args": ["/absolute/path/to/facebook-ads-mcp-server/server.py"],
      "env": {
        "FB_ACCESS_TOKEN": "your_meta_access_token_here"
      }
    }
  }
}

Alternatively, pass the token as a CLI argument:

{
  "mcpServers": {
    "facebook-ads": {
      "command": "python",
      "args": [
        "/absolute/path/to/facebook-ads-mcp-server/server.py",
        "--fb-token",
        "your_meta_access_token_here"
      ]
    }
  }
}

Restart Claude Desktop after saving the config.

Option B: Hosted Server (shared team access)

Run a persistent HTTP server that your whole team connects to via HTTP transport.

Start the server:

FB_ACCESS_TOKEN=your_token python server.py

The server listens on port 8000 by default. Override with the PORT environment variable.

Connect via Claude Desktop:

{
  "mcpServers": {
    "facebook-ads": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Option C: Deploy to Google Cloud Run (recommended for teams)

Deploy:

gcloud run deploy facebook-ads-mcp \
  --source . \
  --region YOUR_REGION \
  --project YOUR_PROJECT_ID \
  --platform managed \
  --port 8000 \
  --allow-unauthenticated \
  --set-env-vars "FB_ACCESS_TOKEN=your_token"

Connect team members via Claude Desktop:

{
  "mcpServers": {
    "facebook-ads": {
      "url": "https://YOUR-SERVICE-URL.run.app/mcp"
    }
  }
}

Environment Variables

Variable	Required	Description
`FB_ACCESS_TOKEN`	Yes (or `--fb-token` arg)	Meta user access token with `ads_read` permission
`PORT`	No	HTTP server port (default: `8000`)

Available Tools

Account

Tool	Description	Example Prompt
`list_ad_accounts`	List all ad accounts linked to your token	"List all my Facebook ad accounts"
`get_details_of_ad_account`	Get details for a specific ad account — spend, balance, currency, status	"What's the current balance and status of ad account act_123456?"

Campaigns

Tool	Description	Example Prompt
`get_campaigns_by_adaccount`	List campaigns in an ad account with optional filters	"Show me all active campaigns in my account"
`get_campaign_by_id`	Get full details for a specific campaign	"What's the objective and budget of campaign 987654321?"
`get_campaign_insights`	Performance metrics for a campaign	"Show me clicks, spend, and ROAS for my top campaign last month"

Ad Sets

Tool	Description	Example Prompt
`get_adsets_by_adaccount`	List all ad sets in an account	"List all ad sets in my account with their budgets"
`get_adsets_by_campaign`	List ad sets within a specific campaign	"What ad sets are running under my Summer Sale campaign?"
`get_adset_by_id`	Get full details for a specific ad set	"Show me the targeting and bid strategy for ad set 555666777"
`get_adsets_by_ids`	Batch fetch multiple ad sets	"Get details for ad sets 111, 222, and 333 at once"
`get_adset_insights`	Performance metrics for an ad set	"What's the CPM and frequency for my retargeting ad set this week?"
`get_targeting_sentence_lines`	Human-readable targeting description for an ad set	"Describe the audience targeting for ad set 555666777 in plain English"
`get_delivery_estimate`	Projected reach and impressions for an ad set	"How many people is my current ad set expected to reach daily?"

Tool	Description	Example Prompt
`get_ads_by_adaccount`	List all ads in an account	"Show me all paused ads in my account"
`get_ads_by_campaign`	List ads within a campaign	"What ads are running in my lead gen campaign?"
`get_ads_by_adset`	List ads within an ad set	"Show me all ads in my retargeting ad set"
`get_ad_by_id`	Get full details for a specific ad	"What creative and status does ad 111222333 have?"
`get_ad_insights`	Performance metrics for an individual ad	"Which of my ads has the lowest cost per result this month?"
`get_ad_previews`	See how an ad renders across placements	"Show me a preview of ad 111222333 in Instagram Story format"

Ad Creatives

Tool	Description	Example Prompt
`get_ad_creative_by_id`	Get details for a specific creative	"What's the headline and body copy for creative 444555666?"
`get_ad_creatives_by_ad_id`	List creatives associated with an ad	"Show me all creatives attached to ad 111222333"
`get_ad_images`	Browse the image library for an account	"List all images in my ad account's creative library"

Insights & Reporting

Tool	Description	Example Prompt
`get_adaccount_insights`	Account-level performance metrics	"Show me total spend, impressions, and purchases for my account last quarter"
`get_campaign_insights`	Campaign-level performance	"Break down my campaign results by age and gender last week"
`get_adset_insights`	Ad set-level performance	"What's the cost per lead for each of my ad sets this month?"
`get_ad_insights`	Ad-level performance	"Rank all my ads by ROAS for the last 30 days"
`fetch_pagination_url`	Fetch the next page of any paginated result	"Get the next page of campaign insights"

Audiences

Tool	Description	Example Prompt
`get_custom_audiences`	List custom audiences (CRM, pixel, lookalike, engagement)	"Show me all my custom audiences and their sizes"
`get_saved_audiences`	List saved audience templates	"What saved audiences do I have available?"
`get_reach_estimate`	Estimate audience size for a targeting spec	"How large is the audience for women 25–44 interested in yoga in the US?"

Targeting Research

Tool	Description	Example Prompt
`search_targeting_options`	Search interests, behaviours, and demographics by keyword	"What targeting interests are available related to 'sustainable fashion'?"
`get_targeting_suggestions`	Get related targeting options based on existing interests	"Suggest more interests similar to the ones I'm already targeting"

Pixels & Conversions

Tool	Description	Example Prompt
`get_pixels`	List Meta Pixels on the account	"What pixels are installed on my ad account?"
`get_custom_conversions`	List custom conversion events	"What custom conversions am I tracking?"

Automation

Tool	Description	Example Prompt
`get_ad_rules`	List automated ad rules	"What automated rules do I have set up?"
`get_ad_rule_history`	See what actions a rule has taken	"Has my auto-pause rule triggered in the last 7 days?"

Organisation

Tool	Description	Example Prompt
`get_ad_labels`	List labels used to tag campaigns, ad sets, and ads	"What labels am I using to organise my ads?"

Lead Generation

Tool	Description	Example Prompt
`get_ad_leads`	Fetch lead form submissions for a Lead Gen ad	"Download all leads submitted through ad 111222333 this month"

Budget

Tool	Description	Example Prompt
`get_minimum_budgets`	Get minimum daily budget requirements by objective	"What's the minimum daily budget I need for a conversions campaign?"

Activity / Change History

Tool	Description	Example Prompt
`get_activities_by_adaccount`	Change history for an ad account	"Who changed the budget on my account last week?"
`get_activities_by_adset`	Change history for a specific ad set	"Show me all changes made to ad set 555666777 in the last 30 days"

Pages

Tool	Description	Example Prompt
`list_pages`	List Facebook Pages the authenticated user manages	"Which Facebook Pages do I have access to?"
`get_page_insights`	Page-level metrics — reach, impressions, engagement, fans	"How many people did my Page reach organically last month?"
`get_page_posts`	Browse published posts on a Page	"Show me the last 20 posts on my Facebook Page"
`get_promotable_posts`	List organic posts eligible to be boosted as ads	"Which of my recent posts can I boost?"

Example Prompts

What's my total ad spend and number of purchases this month?

Which campaigns have the best ROAS over the last 30 days?

Show me all active ad sets with their daily budgets and targeting

Which of my ads has the highest click-through rate this week?

Break down my account performance by age group and gender last quarter

What does the targeting look like for my best-performing ad set, in plain English?

How large is the audience for men aged 30–50 interested in golf in Australia?

Show me all my custom audiences and which ones are large enough to use

Search for targeting interests related to "plant-based diet"

What ads is my competitor running in the US right now? Their page ID is 123456789

Are there any automated rules that have paused my ads recently?

Which organic posts on my Page are eligible to boost?

How has my Facebook Page reach trended over the last 28 days?

Show me all leads submitted through my lead gen campaign this month

What's the minimum daily budget I need for a conversions-objective campaign?

Attribution

Forked from gomarble-ai/facebook-ads-mcp-server, with additions:

FB_ACCESS_TOKEN environment variable support (alongside --fb-token CLI arg)
Streamable HTTP transport for hosted team deployments
20 additional read-only tools: audiences, reach estimates, delivery estimates, targeting research, pixels, custom conversions, image library, ad previews, ad rules, lead gen, page insights, page posts, and page insights/posts

About Dhawal Shah

I run a 40-plus person digital marketing agency out of Singapore, and I build the automation my own teams use. This server is one of those tools rather than a weekend project: it runs against live Meta Ads accounts every week, which is why the read-only surface is wide and the write surface is deliberately narrow.

Fourteen years building companies across Asia behind it. 5,000+ campaigns, 400+ brands, 30+ startups advised, and 300+ training sessions for teams including Sony, Toyota, DHL and Interpol. I am also an Accredited Director with the Singapore Institute of Directors, which in practice means I get asked what breaks, who is accountable and what it costs before anyone asks what it can do.

I write up the routines and agents I actually run at dhawalshah.net.

Worth reading alongside this repo: Google Ads, Meta, LinkedIn & TikTok MCPs for Claude: Agency Setup Guide.

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

NotFair-MetaAds AOAuth
io.github.nowork-studio
Meta Ads MCP (Facebook + Instagram) - analyze performance, manage budgets, pause campaigns.
Marketing Social Media
23,828
AdWeave — Meta Ads MCP ServerOAuth
ai.adweave
Meta Ads MCP server with 47 tools for campaigns, creatives, audiences, and insights.
Marketing Social Media App Automation
2
LemonadoOAuth
io.github.lemonadolabs
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Marketing Research & Data Databases
3
Adextract MCPOAuth
io.github.anuragind003
Search Meta, Google Ads, LinkedIn, and TikTok ad libraries plus creative analysis via MCP.
Marketing Social Media Research & Data
2

Related MCP Servers

Meta Ads MCP Server
Marketing Social Media
brmh
F
license
Not graded
quality
D
maintenance
A comprehensive MCP server for managing and analyzing Meta Ads (Facebook/Instagram) with over 80 natural-language tools for AI agents like Claude Desktop.
Updated 7 months ago (2026-03-06 11:14 UTC)
-
facebook-ads-mcp-server
Marketing Social Media
HeroBrian389
A
license
Not graded
quality
D
maintenance
MCP server for Meta/Facebook Marketing API allowing you to view and manage ad accounts, campaigns, ad sets, ads, and creatives, as well as fetch insights and upload ad images.
Updated 7 months ago (2026-02-26 19:06 UTC)
MIT
mlg-meta-mcp
Marketing Social Media
iammalego
A
license
B
quality
D
maintenance
MCP server for Meta Ads providing 30 tools for account discovery, campaign management, targeting research, and insights. Designed with LLM-friendly outputs and productivity features like cloning and bulk operations.
Updated 5 months ago (2026-04-25 20:07 UTC)
31
1
MIT
Meta Ads MCP
Marketing Social Media
anhnguyen0905
F
license
A
quality
B
maintenance
A read-only MCP server that pulls Meta Ads campaign, ad-set, and ad performance data to help users spot problems and adjust them in Ads Manager.
Updated 2 months ago (2026-07-28 08:24 UTC)
6
-

Facebook / Meta Ads MCP

What you can do

Account & Campaign Management

Performance & Insights

Audiences

Targeting Research

Pixels & Conversions

Creative Library

Automation & Organisation

Lead Generation

Pages

Prerequisites

Step 1: Get a Meta Access Token

Step 2: Local Setup

Step 3: Connect to Claude

Option A: Local (Claude Desktop — single user)

Option B: Hosted Server (shared team access)

Option C: Deploy to Google Cloud Run (recommended for teams)

Environment Variables

Available Tools

Account

Campaigns

Ad Sets

Ads

Ad Creatives

Insights & Reporting

Audiences

Targeting Research

Pixels & Conversions

Automation

Organisation

Lead Generation

Budget

Activity / Change History

Pages

Example Prompts

Attribution

About Dhawal Shah

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Meta Ads MCP Server

facebook-ads-mcp-server

mlg-meta-mcp

Meta Ads MCP