Skip to main content
Glama
mcp-meta-marketing

mcp-meta-marketing

by pauloFroes

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: 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_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

Three installation scopes are available:

Scope

Flag

Config file

Use case

local

-s local

.mcp.json

This project only (default)

project

-s project

.claude/mcp.json

Shared with team via git

user

-s user

~/.claude/mcp.json

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

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


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:

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

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

  3. Click Save Changes

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

3. Generate the token:

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

  2. Select your app in the dropdown

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

  4. Click Generate Token

  5. 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}
  1. 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

Available Tools

18 tools
create_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 AdA
Destructive

Delete an ad. This is irreversible. Consider using update_ad with status=ARCHIVED instead.

Inputs: ad_id (required).

delete_adsetDelete Ad SetA
Destructive

Delete an ad set. This is irreversible. Consider using update_adset with status=ARCHIVED instead.

Inputs: adset_id (required).

delete_campaignDelete CampaignA
Destructive

Delete a campaign. This is irreversible. Consider using update_campaign with status=ARCHIVED instead.

Inputs: campaign_id (required).

get_account_insightsGet Ad Account InsightsA
Read-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 DetailsA
Read-only

Get details of the ad account — name, status, currency, timezone, spend cap, balance, and business info.

Inputs: fields.

get_ad_insightsGet Ad InsightsA
Read-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 InsightsA
Read-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 InsightsA
Read-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 AdsA
Read-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 SetsA
Read-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 CampaignsA
Read-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

    A4.1/5.0

    Scored across 18 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern: get_, list_, create_, update_, delete_. The pattern is predictable and uniform across resources.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Unofficial MCP server implementation for Facebook Business API. Enables LLMs to manage ad campaigns and ads via natural language.
      23 PyPI
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server to manage Meta Ads (Facebook/Instagram) campaigns, ad sets, insights, and audiences from Claude Code using natural language.
      9
      8 npm
      MIT
    • 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.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Python MCP server that exposes Meta Marketing API data, providing tools to manage ad accounts, campaigns, and analytics through natural language interfaces.
      MIT