mcp-meta-marketing
Provides tools for managing Meta (Facebook) advertising campaigns, ad sets, ads, and creatives, as well as retrieving performance insights and account details via the Meta Marketing API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-meta-marketing How much did I spend in the last 7 days?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-meta-marketing
MCP server that wraps the Meta Marketing API (Graph API v25.0) as semantic tools for LLM agents.
Works with Claude Code, Codex, Claude Desktop, Cursor, VS Code, Windsurf, and any MCP-compatible client.
Quick Start
Install in one command — just replace your-token and your-account-id:
claude mcp add meta-marketing -s user \
-e META_ACCESS_TOKEN=your-token \
-e META_AD_ACCOUNT_ID=your-account-id \
-- npx -y github:pauloFroes/mcp-meta-marketingThen just ask in natural language:
Don't have a token yet? See How to get your Access Token below.
Related MCP server: meta-ads-mcp
What you can do
Analyze performance:
"How much did I spend in the last 7 days?"
"Compare CPC and CTR across all active campaigns this month"
"Which ad set has the lowest cost per conversion?"
"Break down last week's results by age and gender"
"What's my overall ROAS this month?"
"Give me a full performance summary of my account for February"Manage campaigns:
"Create a new traffic campaign called 'Summer Sale' with R$50/day budget"
"Pause all campaigns with CPC above R$2.00"
"Duplicate ad set 12345 with a new targeting for ages 18-24"
"Create an ad using creative 67890 in my best performing ad set"
"Archive all campaigns that ended last month"Available Tools
Insights
Tool | Description |
| Get ad account insights with optional level breakdown (campaign/adset/ad) |
| Get insights for a specific campaign |
| Get insights for a specific ad set |
| Get insights for a specific ad |
Listing
Tool | Description |
| List campaigns with status filter and auto-pagination |
| List ad sets, optionally filtered by campaign |
| List ads, optionally filtered by ad set |
| Get ad account details (name, currency, timezone, balance) |
Management
Tool | Description |
| Create a new campaign with objective, budget, and bid strategy |
| Update campaign name, status, budget, or bid strategy |
| Delete a campaign (irreversible) |
| Create an ad set with targeting, budget, and optimization goal |
| Update ad set targeting, budget, status, or schedule |
| Delete an ad set (irreversible) |
| Create an ad linking a creative to an ad set |
| Update ad name, status, or swap creative |
| Delete an ad (irreversible) |
| Create an ad creative (image, video, or carousel) |
Installation
You need two environment variables:
Variable | Description |
| Access token (how to get one) |
| Ad account ID (with or without |
Claude Code
Three installation scopes are available:
Scope | Flag | Config file | Use case |
local |
|
| This project only (default) |
project |
|
| Shared with team via git |
user |
|
| All your projects |
Quick setup (inline env vars):
claude mcp add meta-marketing -s user \
-e META_ACCESS_TOKEN=your-token \
-e META_AD_ACCOUNT_ID=your-account-id \
-- npx -y github:pauloFroes/mcp-meta-marketingReplace
-s userwith-s localor-s projectas needed.
Persistent setup (.env file):
Add to your .mcp.json:
{
"meta-ads": {
"command": "npx",
"args": ["-y", "github:pauloFroes/mcp-meta-ads"],
"env": {
"META_ACCESS_TOKEN": "${META_ACCESS_TOKEN}",
"META_AD_ACCOUNT_ID": "${META_AD_ACCOUNT_ID}"
}
}
}Then define the values in your .env file:
META_ACCESS_TOKEN=your-access-token
META_AD_ACCOUNT_ID=your-ad-account-idSee
.env.examplefor all required variables.
Codex
[mcp_servers.meta-marketing]
command = "npx"
args = ["-y", "github:pauloFroes/mcp-meta-marketing"]
env_vars = ["META_ACCESS_TOKEN", "META_AD_ACCOUNT_ID"]Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"meta-marketing": {
"command": "npx",
"args": ["-y", "github:pauloFroes/mcp-meta-marketing"],
"env": {
"META_ACCESS_TOKEN": "your-token",
"META_AD_ACCOUNT_ID": "your-account-id"
}
}
}
}Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"meta-marketing": {
"command": "npx",
"args": ["-y", "github:pauloFroes/mcp-meta-marketing"],
"env": {
"META_ACCESS_TOKEN": "your-token",
"META_AD_ACCOUNT_ID": "your-account-id"
}
}
}
}VS Code
Add to .vscode/mcp.json in your project:
{
"servers": {
"meta-marketing": {
"command": "npx",
"args": ["-y", "github:pauloFroes/mcp-meta-marketing"],
"env": {
"META_ACCESS_TOKEN": "your-token",
"META_AD_ACCOUNT_ID": "your-account-id"
}
}
}
}Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"meta-marketing": {
"command": "npx",
"args": ["-y", "github:pauloFroes/mcp-meta-marketing"],
"env": {
"META_ACCESS_TOKEN": "your-token",
"META_AD_ACCOUNT_ID": "your-account-id"
}
}
}
}How to get your Access Token
All methods require a Meta App. If you don't have one yet:
Go to developers.facebook.com → My Apps → Create App
Name it (e.g.
ads-marketing-tool) — Meta blocks brand terms like "meta", "fb", "insta" in app namesIn Use cases, filter by "Ads and monetization" and select exactly these two:
"Create and manage ads with the Marketing API" — programmatic campaign management (CRUD)
"Measure ad performance data with the Marketing API" — performance insights and metrics
Do not select "Create and manage app ads with the Meta Ads Manager" — it explicitly does not include Marketing API access.
Associate with your Business Manager (Business Portfolio)
Complete the remaining steps and create the app
Then choose one of the methods below:
Method | Duration | Best for |
A — System User Token | Never expires | Production |
B — Token Debugger | 60 days | Quick setup, no code |
C — Programmatic Exchange | 60 days | Automation / scripts |
Method A — System User Token (recommended, never expires)
Create a new System User or reuse an existing one.
1. Create or pick a System User:
Go to business.facebook.com → Business Settings
Navigate to Users → System Users
Create a new one (Add → name:
mcp-marketing→ role: Admin), or select an existing System User
2. Assign ad account assets:
Click the System User → Add Assets → Ad Accounts
Select the ad account(s) you want to access → permission level: Manage campaigns
Click Save Changes
Without this step the token won't have access to any ad account data.
3. Generate the token:
On the System User page, click Generate New Token
Select your app in the dropdown
Check the scopes:
ads_read,ads_management, andbusiness_managementClick Generate Token
Copy it immediately — it's only shown once
This token never expires unless you revoke it or remove the System User.
Method B — Token Debugger (no code, 60 days)
Quick method entirely in the browser. No System User needed.
Go to your app dashboard at developers.facebook.com → Marketing API → Tools
Select permissions:
ads_readandads_management→ click Get TokenAuthorize when prompted — this generates a short-lived token (~1 hour)
Go to Access Token Debugger
Paste the token → click Debug
At the bottom of the page, click Extend Access Token
Copy the new token — it's valid for 60 days
You'll need to repeat this every ~55 days to keep the token active.
Method C — Programmatic Exchange (automatable, 60 days)
Same result as Method B, but via a single HTTP request — useful for scripts.
Get a short-lived token via Marketing API → Tools (same as Method B, steps 1-3)
Find your App ID and App Secret in your app → Settings → Basic
Make a GET request (browser, curl, or code):
https://graph.facebook.com/v25.0/oauth/access_token?
grant_type=fb_exchange_token&
client_id={APP_ID}&
client_secret={APP_SECRET}&
fb_exchange_token={SHORT_LIVED_TOKEN}The response contains your long-lived
access_token(60 days) andexpires_in
Keep your App Secret safe — never expose it client-side.
License
MIT
Available Tools
18 toolscreate_adCreate AdA
Create a new ad within an ad set. Requires adset_id and a creative_id (create the creative first with create_adcreative).
Inputs: name (required), status (required), adset_id (required), creative_id (required).
create_adcreativeCreate Ad CreativeA
Create an ad creative. The object_story_spec is a JSON string defining the creative content (image, video, or carousel with link_data or video_data). Requires a page_id.
Inputs: name (required), object_story_spec (required).
create_adsetCreate Ad SetA
Create a new ad set within a campaign. Requires campaign_id, targeting, billing_event, optimization_goal, budget, and status. Targeting is a JSON string with age, gender, geo, interests, etc.
Inputs: name (required), status (required), targeting (required), campaign_id (required), +7 more.
create_campaignCreate CampaignA
Create a new campaign. Requires name, objective, and status. Set special_ad_categories to [] if none apply. Budget can be set at campaign level (CBO) or at ad set level.
Inputs: name (required), status (required), objective (required), bid_strategy, +3 more.
delete_adDelete AdADestructive
Delete an ad. This is irreversible. Consider using update_ad with status=ARCHIVED instead.
Inputs: ad_id (required).
delete_adsetDelete Ad SetADestructive
Delete an ad set. This is irreversible. Consider using update_adset with status=ARCHIVED instead.
Inputs: adset_id (required).
delete_campaignDelete CampaignADestructive
Delete a campaign. This is irreversible. Consider using update_campaign with status=ARCHIVED instead.
Inputs: campaign_id (required).
get_account_insightsGet Ad Account InsightsARead-only
Get performance insights for the ad account. Optionally set level=campaign, adset, or ad to break down results. Use since/until for date ranges. Returns metrics like impressions, clicks, spend, cpc, cpm, ctr, reach.
Inputs: level, limit, since, until, +4 more.
get_ad_accountGet Ad Account DetailsARead-only
Get details of the ad account — name, status, currency, timezone, spend cap, balance, and business info.
Inputs: fields.
get_ad_insightsGet Ad InsightsARead-only
Get performance insights for a specific ad by ID. Returns metrics like impressions, clicks, spend, cpc, cpm, ctr, reach.
Inputs: ad_id (required), limit, since, until, +4 more.
get_adset_insightsGet Ad Set InsightsARead-only
Get performance insights for a specific ad set by ID. Returns metrics like impressions, clicks, spend, cpc, cpm, ctr, reach.
Inputs: adset_id (required), limit, since, until, +4 more.
get_campaign_insightsGet Campaign InsightsARead-only
Get performance insights for a specific campaign by ID. Returns metrics like impressions, clicks, spend, cpc, cpm, ctr, reach.
Inputs: campaign_id (required), limit, since, until, +4 more.
list_adsList AdsARead-only
List ads in the ad account. Optionally filter by ad set ID or effective status. Returns ad name, status, creative, and tracking info. Auto-paginates up to 10 pages.
Inputs: limit, fields, adset_id, effective_status.
list_adsetsList Ad SetsARead-only
List ad sets in the ad account. Optionally filter by campaign ID or effective status. Returns ad set name, status, targeting, budget, and schedule. Auto-paginates up to 10 pages.
Inputs: limit, fields, campaign_id, effective_status.
list_campaignsList CampaignsARead-only
List campaigns in the ad account. Returns campaign name, status, objective, daily/lifetime budget, and bid strategy. Use effective_status to filter. Auto-paginates up to 10 pages.
Inputs: limit, fields, effective_status.
update_adUpdate AdA
Update an existing ad. Change name, status, or swap creative.
Inputs: ad_id (required), name, status, creative_id.
update_adsetUpdate Ad SetA
Update an existing ad set. Send only the fields you want to change.
Inputs: adset_id (required), name, status, end_time, +4 more.
update_campaignUpdate CampaignA
Update an existing campaign. Send only the fields you want to change. Cannot change objective after creation.
Inputs: campaign_id (required), name, status, bid_strategy, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool targets a distinct resource and action, with clear separation between account, campaign, adset, ad, and creative operations. The four insights tools are differentiated by hierarchy level, and CRUD tools are resource-specific. No meaningful overlap.
All tools follow a consistent verb_noun snake_case pattern: get_, list_, create_, update_, delete_. The pattern is predictable and uniform across resources.
18 tools is on the higher side but justified by the complexity of the Meta marketing domain. Each tool covers a necessary operation for the hierarchy of account, campaign, adset, ad, and creative.
Core lifecycle (create/update/delete/list/insights) is well-covered for campaigns, adsets, and ads. Gaps include creative management (only create, no update/list/delete) and no single-resource getters, but these are minor workarounds.
Maintenance
Related MCP Connectors
Meta Ads MCP server: run Facebook and Instagram campaigns, ad sets, ads and reports from AI.
Hosted Meta Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted MCP server for marketing agencies: connect Google Ads, GA4, Search Console, Meta, LinkedIn and more to Claude or ChatGPT. Pull reports and make changes via OAuth login, no setup.
Google Ads MCP server: run Search, Display, Demand Gen and PMax campaigns from AI.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceUnofficial MCP server implementation for Facebook Business API. Enables LLMs to manage ad campaigns and ads via natural language.23 PyPI2MIT
- AlicenseAqualityDmaintenanceMCP server to manage Meta Ads (Facebook/Instagram) campaigns, ad sets, insights, and audiences from Claude Code using natural language.98 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP 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.MIT
- AlicenseNot gradedqualityDmaintenancePython MCP server that exposes Meta Marketing API data, providing tools to manage ad accounts, campaigns, and analytics through natural language interfaces.MIT