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 \
  --transport stdio \
  -e META_ACCESS_TOKEN=your-token \
  -e META_AD_ACCOUNT_ID=your-account-id \
  -- npx -y github:pauloFroes/mcp-meta-marketing

Then just ask in natural language:

Don't have a token yet? See How to get your Access Token below.

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_account_insights | Get ad account insights with optional level breakdown (campaign/adset/ad) | | get_campaign_insights | Get insights for a specific campaign | | get_adset_insights | Get insights for a specific ad set | | get_ad_insights | Get insights for a specific ad |

Listing

| Tool | Description | | --- | --- | | list_campaigns | List campaigns with status filter and auto-pagination | | list_adsets | List ad sets, optionally filtered by campaign | | list_ads | List ads, optionally filtered by ad set | | get_ad_account | Get ad account details (name, currency, timezone, balance) |

Management

| Tool | Description | | --- | --- | | create_campaign | Create a new campaign with objective, budget, and bid strategy | | update_campaign | Update campaign name, status, budget, or bid strategy | | delete_campaign | Delete a campaign (irreversible) | | create_adset | Create an ad set with targeting, budget, and optimization goal | | update_adset | Update ad set targeting, budget, status, or schedule | | delete_adset | Delete an ad set (irreversible) | | create_ad | Create an ad linking a creative to an ad set | | update_ad | Update ad name, status, or swap creative | | delete_ad | Delete an ad (irreversible) | | create_adcreative | Create an ad creative (image, video, or carousel) |

Installation

You need two environment variables:

| Variable | Description | | --- | --- | | META_ACCESS_TOKEN | Access token (how to get one) | | META_AD_ACCOUNT_ID | Ad account ID (with or without act_ prefix — find it in the Ads Manager URL: act_XXXXXXXXX) |

Claude Code

claude mcp add meta-marketing \
  --transport stdio \
  -e META_ACCESS_TOKEN=your-token \
  -e META_AD_ACCOUNT_ID=your-account-id \
  -- npx -y github:pauloFroes/mcp-meta-marketing

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 names
In 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, and business_management
Click 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_read and ads_management → click Get Token
Authorize 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) and expires_in

Keep your App Secret safe — never expose it client-side.

License

MIT

MCP Servers