meta-mcp

Comprehensive Meta Ads MCP Server — 77 tools for full campaign lifecycle management

A production-ready Model Context Protocol (MCP) server that gives AI assistants like Claude complete control over Meta (Facebook & Instagram) advertising operations. Manage campaigns, ad sets, ads, creatives, audiences, conversions, pixels, and more — all through natural language.

---

Table of Contents

• Overview
• Features
• Complete Tool Reference (77 Tools)
• Prerequisites
• Installation
• Claude Code Setup
• Usage Examples
• REST API
• Architecture
• Deployment
• Configuration Reference
• Rate Limiting
• License

---

Overview

meta-mcp bridges the gap between AI assistants and the Meta Marketing API. It exposes 77 tools across 24 modules, covering the entire ad campaign lifecycle — from account discovery and campaign creation to performance analytics and automated optimization rules.

Dual Interface

The server provides two access modes:

| Interface | Endpoint | Use Case | |-----------|----------|----------| | MCP Protocol | /mcp | Claude Code, Claude Desktop, any MCP client | | REST API | /api/v1/* | n8n, Postman, curl, custom apps, webhooks |

Both interfaces share the same underlying Meta API client with built-in rate limiting, retry logic, and error handling.

---

Features

Campaign Management

• Full CRUD for campaigns, ad sets, ads, and creatives
• Copy campaigns, ad sets, and ads with all their settings
• Budget scheduling and automated rules
• Ad preview generation

Audience & Targeting

• Custom audience creation (website, app, customer list, engagement, offline)
• Lookalike audience generation
• Saved audience management
• Interest, behavior, demographic, and geo-location search
• Targeting validation and reach estimation

Analytics & Tracking

• Performance insights at account, campaign, ad set, and ad levels
• Async report generation for large datasets
• Meta Pixel management
• Server-side conversion tracking (Conversions API)
• Custom conversion rules
• Activity audit logs

Media & Creative

• Image upload and management
• Video upload with thumbnail extraction
• Ad creative creation with Object Story Spec
• Ad preview rendering

Automation & Operations

• Automated rules (pause low performers, adjust budgets, send notifications)
• Batch API (up to 50 sub-requests per call)
• Label management for organization
• Lead generation form access

Enterprise-Ready

• BUC (Business Use Case) rate limiting with adaptive throttling
• Automatic retry with exponential backoff
• Session management with 30-minute TTL
• Optional API key authentication
• Docker containerization

---

Complete Tool Reference (77 Tools)

Account Management (4 tools)

| Tool | Description | |------|-------------| | get_ad_accounts | List all accessible ad accounts for the authenticated user | | get_account_info | Get detailed information about a specific ad account | | get_account_pages | List Facebook Pages associated with an ad account | | get_delivery_estimate | Estimate delivery reach for a given targeting specification |

Campaigns (5 tools)

| Tool | Description | |------|-------------| | list_campaigns | List campaigns with filtering by status, objective, date range | | get_campaign | Get full details of a single campaign | | create_campaign | Create a new campaign with objective, budget, and settings | | update_campaign | Modify campaign properties (name, status, budget, bid strategy) | | delete_campaign | Permanently delete a campaign |

Ad Sets (5 tools)

| Tool | Description | |------|-------------| | list_adsets | List ad sets with filtering by campaign, status, date range | | get_adset | Get full details of a single ad set including targeting | | create_adset | Create a new ad set with targeting, budget, schedule, and placement | | update_adset | Modify ad set properties (targeting, budget, bid, schedule) | | delete_adset | Permanently delete an ad set |

Ads (5 tools)

| Tool | Description | |------|-------------| | list_ads | List ads with filtering by ad set, campaign, status | | get_ad | Get full details of a single ad including creative reference | | create_ad | Create a new ad linking to an existing creative and ad set | | update_ad | Modify ad properties (name, status, creative, tracking) | | delete_ad | Permanently delete an ad |

Creatives (5 tools)

| Tool | Description | |------|-------------| | list_creatives | List ad creatives with filtering options | | get_creative | Get full details of a single creative including asset URLs | | create_creative | Create a new ad creative with Object Story Spec | | update_creative | Modify creative properties | | delete_creative | Permanently delete a creative |

Images (3 tools)

| Tool | Description | |------|-------------| | upload_image | Upload an image file to the ad account's image library | | list_images | List all images in the ad account's library | | delete_image | Delete an image from the library by hash |

Videos (4 tools)

| Tool | Description | |------|-------------| | upload_video | Upload a video file to the ad account | | list_videos | List all videos in the ad account | | get_video | Get details of a specific video | | get_video_thumbnails | Retrieve auto-generated thumbnails for a video |

Custom Audiences (6 tools)

| Tool | Description | |------|-------------| | list_custom_audiences | List custom audiences in the ad account | | create_custom_audience | Create a custom audience (website, app, customer list, engagement, offline) | | add_audience_users | Upload hashed PII (email, phone, etc.) to a custom audience | | remove_audience_users | Remove users from a custom audience by hashed PII | | create_lookalike_audience | Create a lookalike audience from a source audience | | delete_audience | Permanently delete a custom audience |

Saved Audiences (3 tools)

| Tool | Description | |------|-------------| | list_saved_audiences | List saved audience segments | | create_saved_audience | Create a reusable saved audience with targeting spec | | delete_saved_audience | Delete a saved audience |

Insights & Analytics (3 tools)

| Tool | Description | |------|-------------| | get_insights | Get performance metrics for campaigns, ad sets, or ads with breakdowns | | get_account_insights | Get account-level aggregated performance metrics | | create_async_report | Create an async report job for large data exports |

Targeting Search (4 tools)

| Tool | Description | |------|-------------| | search_interests | Search for interest-based targeting options by keyword | | search_behaviors | Search for behavior-based targeting options | | search_geo_locations | Search for geographic targeting (countries, cities, regions, zips) | | search_demographics | Search for demographic targeting options |

Targeting Utilities (3 tools)

| Tool | Description | |------|-------------| | get_targeting_suggestions | Get AI-suggested targeting options based on your input | | validate_targeting | Validate a targeting spec before using it | | get_targeting_sentence | Convert a targeting spec to human-readable description |

Conversions API (1 tool)

| Tool | Description | |------|-------------| | send_conversion_event | Send server-side conversion events via the Conversions API |

Custom Conversions (4 tools)

| Tool | Description | |------|-------------| | list_custom_conversions | List URL-based custom conversion rules | | create_custom_conversion | Create a custom conversion rule (URL contains, equals, regex) | | get_custom_conversion | Get details of a specific custom conversion | | delete_custom_conversion | Delete a custom conversion rule |

Meta Pixels (2 tools)

| Tool | Description | |------|-------------| | list_pixels | List Meta Pixels in the ad account | | get_pixel | Get details and stats for a specific pixel |

Lead Generation (2 tools)

| Tool | Description | |------|-------------| | get_lead_forms | List lead generation forms for a Facebook Page | | get_leads | Retrieve submitted leads from a lead gen form |

Automated Rules (5 tools)

| Tool | Description | |------|-------------| | list_ad_rules | List automated rules in the ad account | | create_ad_rule | Create an automation rule (pause ads, adjust budget, send notifications) | | get_ad_rule | Get details of a specific rule | | update_ad_rule | Modify an existing rule's conditions, actions, or schedule | | delete_ad_rule | Delete an automated rule |

Ad Previews (2 tools)

| Tool | Description | |------|-------------| | get_ad_previews | Get preview renders for an existing ad | | generate_ad_preview | Generate a preview from a creative spec (without creating an ad) |

Copy Operations (3 tools)

| Tool | Description | |------|-------------| | copy_campaign | Duplicate a campaign with all its settings | | copy_adset | Duplicate an ad set with targeting and budget | | copy_ad | Duplicate an ad with its creative reference |

Batch Operations (1 tool)

| Tool | Description | |------|-------------| | batch_request | Execute up to 50 Graph API sub-requests in a single call |

Labels (3 tools)

| Tool | Description | |------|-------------| | list_ad_labels | List labels used for organizing campaigns/ads | | create_ad_label | Create a new organizational label | | delete_ad_label | Delete a label |

Budget Schedules (2 tools)

| Tool | Description | |------|-------------| | get_budget_schedules | List budget schedules for a campaign | | create_budget_schedule | Create a time-based budget schedule |

Activities (1 tool)

| Tool | Description | |------|-------------| | get_account_activities | Get the audit log of actions taken on the ad account |

Reach Estimation (1 tool)

| Tool | Description | |------|-------------| | get_reach_estimate | Estimate potential reach and frequency for a targeting spec |

---

Prerequisites

1. Node.js 22+ — Download
2. Meta Developer Account — developers.facebook.com
3. Meta Access Token — System User token or long-lived User token with ads_management and ads_read permissions
4. Ad Account ID — Your Meta ad account ID (format: act_123456789)

Getting a Meta Access Token

1. Go to Meta Business Suite > System Users
2. Create a System User (or use existing)
3. Assign the System User to your ad account with Admin role
4. Generate a token with these permissions:

• ads_management — Create and manage ads
• ads_read — Read ad account data
• pages_read_engagement — Access Page data (for creatives)
• leads_retrieval — Access lead gen form data (optional)

---

Installation

Local Development

# Clone the repository
git clone https://github.com/serkanhaslak/meta-mcp.git
cd meta-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your Meta credentials

# Run in development mode (with hot reload)
npm run dev

# Or build and run production
npm run build
npm start

Docker

# Build the image
docker build -t meta-mcp .

# Run the container
docker run -p 3000:3000 \
  -e MCP_API_KEY=your_api_key \
  -e META_ACCESS_TOKEN=your_token \
  -e META_AD_ACCOUNT_ID=act_123456789 \
  meta-mcp

Note: META_ACCESS_TOKEN is a fallback — callers can override it per session/request via the X-Meta-Token header.

The server starts at https://meta-mcp.pragmaticgrowth.com (or http://localhost:3000 locally) with:

• MCP endpoint: https://meta-mcp.pragmaticgrowth.com/mcp
• REST API: https://meta-mcp.pragmaticgrowth.com/api/v1/*
• Health check: https://meta-mcp.pragmaticgrowth.com/health
• API docs: https://meta-mcp.pragmaticgrowth.com/docs

---

Claude Code Setup

Option 1: Remote Server (Recommended)

Connect Claude Code directly to the remote endpoint.

1. Add your secrets to .env (gitignored, never committed):

META_MCP_URL=https://your-deployment-url.up.railway.app/mcp
MCP_API_KEY=your_api_key_here
META_ACCESS_TOKEN=your_meta_access_token_here

1. Create or edit .mcp.json in your project root (or ~/.claude/.mcp.json for global access):

{
  "mcpServers": {
    "meta-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "${META_MCP_URL}",
        "--header",
        "Authorization: Bearer ${MCP_API_KEY}",
        "--header",
        "X-Meta-Token: ${META_ACCESS_TOKEN}"
      ]
    }
  }
}

The ${...} variables are resolved from your .env file — no secrets in .mcp.json. The X-Meta-Token header provides your Meta access token per session, using the same auth model as the REST API.

Option 2: Local Server (stdio)

Run the MCP server locally as a subprocess:

{
  "mcpServers": {
    "meta-mcp": {
      "command": "node",
      "args": ["/path/to/meta-mcp/dist/index.js"],
      "env": {
        "META_ACCESS_TOKEN": "your_meta_access_token",
        "META_AD_ACCOUNT_ID": "act_123456789"
      }
    }
  }
}

Note: For the local stdio option, build first with npm run build.

Option 3: Development Mode (stdio with tsx)

For active development with TypeScript source:

{
  "mcpServers": {
    "meta-mcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/meta-mcp/src/index.ts"],
      "env": {
        "META_ACCESS_TOKEN": "your_meta_access_token",
        "META_AD_ACCOUNT_ID": "act_123456789"
      }
    }
  }
}

Claude Code Permissions

To auto-allow all meta-mcp tools, add to your .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__meta-mcp__*"
    ]
  }
}

Or allow specific tool categories:

{
  "permissions": {
    "allow": [
      "mcp__meta-mcp__list_*",
      "mcp__meta-mcp__get_*",
      "mcp__meta-mcp__search_*"
    ],
    "deny": [
      "mcp__meta-mcp__delete_*"
    ]
  }
}

Claude Desktop Setup

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "meta-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-deployment-url.up.railway.app/mcp",
        "--header",
        "Authorization: Bearer YOUR_MCP_API_KEY",
        "--header",
        "X-Meta-Token: YOUR_META_ACCESS_TOKEN"
      ]
    }
  }
}

Note: Claude Desktop doesn't support ${ENV_VAR} syntax, so you must paste the actual values.

Verifying the Connection

After configuring, start Claude Code and ask:

What Meta Ads tools do you have access to?

Claude should list all 77 tools organized by category.

---

Usage Examples

Create a Complete Campaign

Create a new Meta Ads campaign:
- Objective: OUTCOME_LEADS
- Name: "Spring Sale 2025"
- Daily budget: $50
- Target: US, ages 25-45, interested in "Online Shopping"
- Use my Page for the creative with headline "50% Off Everything"
- Start running immediately

Claude will use create_campaign, create_adset, create_creative, and create_ad in sequence.

Analyze Performance

Show me the performance of all active campaigns for the last 7 days.
Break down by age and gender. Include spend, impressions, clicks, CPC, and ROAS.

Claude will use get_insights with the appropriate date range and breakdowns.

Audience Management

Create a lookalike audience based on my "High Value Customers" custom audience.
Target the US with 1% similarity. Then create an ad set using this audience.

Claude will use create_lookalike_audience followed by create_adset.

Automated Optimization

Create a rule that pauses any ad with CPC above $5 and more than 1000 impressions.
Check every 30 minutes. Send me a notification when it triggers.

Claude will use create_ad_rule with the appropriate conditions and actions.

Batch Operations

Get the status and spend of all 25 campaigns in my account using a single batch request.

Claude will use batch_request to execute multiple API calls efficiently.

Copy and Iterate

Copy my best performing campaign "Summer Promo" and create a variant
with a different headline for A/B testing.

Claude will use copy_campaign and then modify the creative.

---

REST API

The server also exposes a REST API for non-MCP clients (n8n, Postman, curl, custom apps).

Authentication

Both MCP and REST use the same per-caller auth model. All /mcp and /api/* requests use these headers:

| Header | Purpose | |--------|---------| | Authorization: Bearer <MCP_API_KEY> | Server API key — gates access to all endpoints | | X-Meta-Token: <token> | Meta access token — authenticates with Meta Graph API | | X-Meta-Account-Id: <id> | Default ad account for this session/request (optional) |

For MCP, X-Meta-Token and X-Meta-Account-Id are read once at session creation (initial POST /mcp) and persist for the session lifetime. For REST, they are read per request.

If X-Meta-Token is not provided, the server falls back to the META_ACCESS_TOKEN environment variable.

curl -H "Authorization: Bearer YOUR_MCP_API_KEY" \
     -H "X-Meta-Token: YOUR_META_TOKEN" \
     -H "X-Meta-Account-Id: act_123456789" \
     https://meta-mcp.pragmaticgrowth.com/api/v1/campaigns

Convenience Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/v1/accounts | List ad accounts | | GET | /api/v1/campaigns | List campaigns | | POST | /api/v1/campaigns | Create campaign | | GET | /api/v1/campaigns/:id | Get campaign | | PUT | /api/v1/campaigns/:id | Update campaign | | DELETE | /api/v1/campaigns/:id | Delete campaign | | GET | /api/v1/adsets | List ad sets | | POST | /api/v1/adsets | Create ad set | | GET | /api/v1/ads | List ads | | POST | /api/v1/ads | Create ad | | GET | /api/v1/creatives | List creatives | | GET | /api/v1/insights | Get insights | | ... | ... | Full CRUD for all resources |

Generic Graph API Proxy

Access any Meta Graph API endpoint directly:

# Get user's ad accounts
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "X-Meta-Token: YOUR_META_TOKEN" \
     "https://meta-mcp.pragmaticgrowth.com/api/v1/meta/me/adaccounts?fields=id,name&limit=5"

# Get campaign insights
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "X-Meta-Token: YOUR_META_TOKEN" \
     "https://meta-mcp.pragmaticgrowth.com/api/v1/meta/act_123/insights?fields=spend,impressions&date_preset=last_7d"

Health Check

curl https://meta-mcp.pragmaticgrowth.com/health

Returns: ``json { "status": "ok", "name": "meta-mcp", "version": "1.0.0", "tools": 77, "modes": ["mcp", "rest"], "uptime": 3600.5 } ``

---

Architecture

Tech Stack

| Component | Technology | |-----------|-----------| | Runtime | Node.js 22 | | Language | TypeScript 5.9 (strict mode) | | HTTP Server | Fastify 5 | | MCP Protocol | @modelcontextprotocol/sdk 1.27 | | Validation | Zod 3.25 | | Meta API | Graph API v21.0 |

Project Structure

meta-mcp/
├── src/
│   ├── index.ts              # Server entry — Fastify setup, MCP endpoint, session management
│   ├── client.ts             # MetaApiClient — Graph API wrapper with retries and rate limiting
│   ├── types.ts              # TypeScript interfaces for API responses
│   ├── tools/                # 24 tool modules (77 total tools)
│   │   ├── index.ts          # Tool registration hub
│   │   ├── account.ts        # Account management tools
│   │   ├── campaigns.ts      # Campaign CRUD
│   │   ├── adsets.ts         # Ad set management
│   │   ├── ads.ts            # Ad management
│   │   ├── creatives.ts      # Creative assets
│   │   ├── images.ts         # Image upload/management
│   │   ├── videos.ts         # Video upload/management
│   │   ├── audiences.ts      # Custom & lookalike audiences
│   │   ├── saved-audiences.ts# Saved audience segments
│   │   ├── insights.ts       # Performance analytics
│   │   ├── targeting.ts      # Interest/behavior/geo/demo search
│   │   ├── targeting-utils.ts# Targeting validation & suggestions
│   │   ├── conversions.ts    # Conversions API (server-side tracking)
│   │   ├── custom-conversions.ts # URL-based conversion rules
│   │   ├── pixel.ts          # Meta Pixel management
│   │   ├── leadgen.ts        # Lead generation forms
│   │   ├── rules.ts          # Automated rules
│   │   ├── previews.ts       # Ad preview rendering
│   │   ├── copies.ts         # Campaign/adset/ad duplication
│   │   ├── batch.ts          # Batch API operations
│   │   ├── labels.ts         # Label management
│   │   ├── budget-schedules.ts # Budget scheduling
│   │   ├── activities.ts     # Audit activity logs
│   │   └── reach-estimate.ts # Reach/frequency estimation
│   ├── landing.ts            # Landing page HTML (served at /)
│   ├── swagger-theme.ts      # Dark theme CSS for Swagger UI
│   ├── rest/
│   │   ├── proxy.ts          # REST API routes and Graph API proxy
│   │   └── schemas.ts        # Zod schemas for OpenAPI documentation
│   └── utils/
│       ├── default-fields.ts # Pre-configured API field selections
│       ├── rate-limiter.ts   # BUC-based adaptive rate limiting
│       ├── pagination.ts     # Cursor-based pagination helper
│       ├── sleep.ts          # Async delay utility
│       └── tool-response.ts  # Response formatting helpers
├── .env.example              # Environment variable template
├── .mcp.json.example         # MCP client configuration template
├── Dockerfile                # Docker containerization
├── package.json              # Dependencies and scripts
└── tsconfig.json             # TypeScript configuration

How It Works

┌─────────────┐     MCP Protocol      ┌──────────────┐     Graph API     ┌──────────────┐
│ Claude Code  │◄────── /mcp ────────►│   meta-mcp   │◄───────────────►│  Meta API    │
│ Claude Desktop│   (Streamable HTTP)  │   (Fastify)  │   (Rate-limited) │ graph.fb.com │
└─────────────┘                        └──────────────┘                  └──────────────┘
                                             ▲
┌─────────────┐     REST API           │
│ n8n / curl  │◄── /api/v1/* ─────────┘
│ Postman     │   (JSON over HTTP)
└─────────────┘

1. Claude sends a tool call (e.g., list_campaigns) via the MCP protocol
2. meta-mcp validates parameters with Zod, constructs the Graph API request
3. MetaApiClient applies rate limiting, sends the request, handles retries
4. Response is formatted and returned to Claude via MCP

---

Deployment

Railway (One-Click)

1. Fork this repository
2. Connect your GitHub repo to Railway
3. Add environment variables:

• MCP_API_KEY — Protect the endpoint with an API key (recommended)
• META_ACCESS_TOKEN — Fallback Meta API token (optional if callers send X-Meta-Token header)
• META_AD_ACCOUNT_ID — Fallback default ad account (optional)

1. Deploy — Railway will auto-detect the Dockerfile

Docker Compose

version: "3.8"
services:
  meta-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - MCP_API_KEY=${MCP_API_KEY}
      - META_ACCESS_TOKEN=${META_ACCESS_TOKEN}  # optional fallback
      - META_AD_ACCOUNT_ID=${META_AD_ACCOUNT_ID}  # optional fallback
      - PORT=3000
    restart: unless-stopped

Environment Variables

# Start with env vars directly
MCP_API_KEY=your_secret_key \
META_ACCESS_TOKEN=your_token \
META_AD_ACCOUNT_ID=act_123456789 \
PORT=3000 \
node dist/index.js

---

Configuration Reference

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | MCP_API_KEY | Recommended | — | API key for authenticating all /mcp and /api/* requests. If not set, endpoints are open | | META_ACCESS_TOKEN | No | — | Fallback Meta API token. Used when callers don't provide X-Meta-Token header | | META_AD_ACCOUNT_ID | No | — | Fallback default ad account ID (e.g., act_123456789). Overridden by X-Meta-Account-Id header | | META_API_VERSION | No | v28.0 | Meta Graph API version override | | PORT | No | 3000 | Server listening port | | META_MCP_URL | No | — | Server URL for .mcp.json env var interpolation (e.g., https://your-app.up.railway.app/mcp) |

---

Rate Limiting

meta-mcp implements intelligent rate limiting based on Meta's Business Use Case (BUC) system:

• Parses BUC headers from every Meta API response (x-business-use-case-usage)
• Monitors three metrics: call count, CPU time, total time
• Adaptive throttling: Automatically slows down when any metric exceeds 75% of the limit
• Minimum delay: 200ms between requests to avoid burst patterns
• Automatic retry: Failed requests retry with exponential backoff (1s, 2s, 4s) up to 3 times
• Transient error handling: Automatically retries on 429 (rate limit), 500, 502, 503 errors

This means you can issue many tool calls without worrying about hitting Meta's rate limits — the server handles throttling transparently.

---

License

ISC