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-marketing

Then just ask in natural language:

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

Related MCP server: facebook-business-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

Listing

Management

Installation

You need two environment variables:

Claude Code

Three installation scopes are available:

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-marketing

Replace -s user with -s local or -s project as 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-id

See .env.example for 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:

1. Go to developers.facebook.com → My Apps → Create App

2. Name it (e.g. ads-marketing-tool) — Meta blocks brand terms like "meta", "fb", "insta" in app names

3. 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.

4. Associate with your Business Manager (Business Portfolio)

5. Complete the remaining steps and create the app

Then choose one of the methods below:

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:

1. Go to business.facebook.com → Business Settings

2. Navigate to Users → System Users

3. Create a new one (Add → name: mcp-marketing → role: Admin), or select an existing System User

2. Assign ad account assets:

4. Click the System User → Add Assets → Ad Accounts

5. Select the ad account(s) you want to access → permission level: Manage campaigns

6. Click Save Changes

Without this step the token won't have access to any ad account data.

3. Generate the token:

7. On the System User page, click Generate New Token

8. Select your app in the dropdown

9. Check the scopes: ads_read, ads_management, and business_management

10. Click Generate Token

11. 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.

1. Go to your app dashboard at developers.facebook.com → Marketing API → Tools

2. Select permissions: ads_read and ads_management → click Get Token

3. Authorize when prompted — this generates a short-lived token (~1 hour)

4. Go to Access Token Debugger

5. Paste the token → click Debug

6. At the bottom of the page, click Extend Access Token

7. 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.

1. Get a short-lived token via Marketing API → Tools (same as Method B, steps 1-3)

2. Find your App ID and App Secret in your app → Settings → Basic

3. 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}

4. 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