Meta Marketing API MCP Server

A Meta Ads MCP server plus agent bundle for Codex and Claude Code. The package provides the Meta API server, skill prompts, Claude slash commands, and local workspace initialization for site profiles and business-specific rules.

⚡ Quick Start

1) Install

npm install -g @edvintoome/meta-mcp

2) Configure (Claude Desktop / Cursor)

Create or edit your MCP config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Minimal config:

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@edvintoome/meta-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

If your app requires appsecret_proof, add META_APP_SECRET:

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@edvintoome/meta-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here",
        "META_APP_SECRET": "your_app_secret"
      }
    }
  }
}

3) Restart your client

• Claude Desktop: quit and reopen
• Cursor: restart the IDE

4) Verify

Restart your MCP client, then call the health_check tool from the client.

Agent Bundle

This repo now ships as a Meta Ads agent bundle around the local meta MCP server.

Bundled skills:

• meta-ads-builder
• meta-ads-consultant
• meta-ads-morning-review
• meta-ad-copy
• supporting ad-creative
• supporting paid-ads

Tracked starter files:

• site-profiles.example.json
• BUSINESS_RULES.example.md

Local runtime files:

• site-profiles.local.json
• BUSINESS_RULES.local.md

Create the local runtime files with:

npm run init:workspace

Codex Plugin

Codex plugin discovery now uses the standard repo-local layout:

• plugin bundle: plugins/meta-mcp
• workspace marketplace: .agents/plugins/marketplace.json

Open this repo in Codex and the plugin can be discovered from the local workspace marketplace.

If you want it available outside this repo too, run:

npm run setup:codex-plugin

That installer:

• creates ~/plugins/meta-mcp as a link to this repo
• writes ~/.agents/plugins/marketplace.json
• enables meta-mcp@meta-mcp-local in ~/.codex/config.toml

If you are using the published package instead of a clone, you can also install it with:

npx -y @edvintoome/meta-mcp install-codex-plugin

Codex + Meta Skills

This repo ships repo-local skills under skills/.

Use npm run setup:codex to wire both pieces together:

• installs all repo Meta skills into ~/.codex/skills
• updates ~/.codex/config.toml with a local meta MCP server pointing at src/index.ts
• reuses the meta namespace the skills expect, so mcp__meta__... calls resolve without extra mapping

Why this split works:

• the skills are the orchestration layer
• the MCP server is the execution layer that talks to Meta
• keeping the skills symlinked to the repo means skill updates ship with the repo and do not need manual copying

After setup, restart Codex and use prompts like:

Use $meta-ads-builder to publish a paused Meta ad from /absolute/path/to/image.jpg for the selected site profile

The builder skill will:

• call health_check and get_capabilities
• resolve the matching site profile from site-profiles.local.json
• use the selected image or enumerate image candidates from your working folder
• persist meta-ads-brief.json and meta-ads-result.json in the working folder

The consultant and morning-review skills use the same MCP server and site profiles for diagnosis, daily reporting, creative feedback, and optimization advice.

🚀 Features

Campaign Management

• ✅ Create, update, pause, resume, and delete campaigns
• ✅ Support for all campaign objectives (traffic, conversions, awareness, etc.)
• ✅ Budget management and scheduling
• ✅ Ad set creation with advanced targeting
• ✅ Individual ad management

Analytics & Reporting

• 📊 Performance insights with customizable date ranges
• 📈 Multi-object performance comparison
• 📋 Data export in CSV/JSON formats
• 🎯 Attribution modeling and conversion tracking
• 📅 Daily performance trends analysis

Audience Management

• 👥 Custom audience creation and management
• 🎯 Lookalike audience generation
• 📏 Audience size estimation
• 🔍 Targeting recommendations and insights
• 🏥 Audience health monitoring

Creative Management

• 🎨 Ad creative creation and management
• 👁️ Cross-platform ad previews
• 🧪 A/B testing setup and guidance
• 📸 Creative performance analysis

Enterprise Features

• 🔐 Secure OAuth 2.0 authentication
• ⚡ Automatic rate limiting with exponential backoff
• 🔄 Pagination support for large datasets
• 🛡️ Comprehensive error handling
• 📚 Rich MCP resources for contextual data access
• 🌐 Multi-account support

📦 Installation & Setup

Option 1: Direct Installation (Recommended)

npm install -g @edvintoome/meta-mcp

Option 2: From Source

git clone https://github.com/EdvinToome/meta-mcp.git
cd meta-mcp
npm install
npm run build

Option 3: Automated Setup (Easiest)

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

# Run the interactive setup
npm run setup

The setup script will:

• ✅ Check system requirements
• ✅ Validate your Meta access token
• ✅ Create Claude Desktop configuration
• ✅ Install dependencies
• ✅ Test the connection

Codex Setup

If you want Codex to use this MCP server together with the bundled Meta skills:

npm install
npm run setup:codex

The installer uses a local source setup:

• MCP server command: node_modules/.bin/tsx src/index.ts
• Codex MCP server name: meta
• skill install target: ~/.codex/skills/*

If you already have different skills at those targets, re-run with --force to replace them:

npm run setup:codex -- --force

Claude Code Setup

Claude Code can use the same repo directly:

• .mcp.json exposes the local meta MCP server
• CLAUDE.md provides project instructions
• .claude/commands/ provides ready-to-use slash commands
• the local server still expects META_ACCESS_TOKEN and optional META_APP_* variables in the shell that launches Claude Code
• local business data should live in site-profiles.local.json and BUSINESS_RULES.local.md

Example commands after opening the repo in Claude Code:

• /meta-ads-builder
• /meta-ads-consultant
• /meta-ads-morning-review
• /meta-ad-copy

To install the Meta bundle into another Claude Code project:

npm run setup:claude -- --project /absolute/path/to/project

That installer:

• merges a local meta server into the target project's .mcp.json
• installs Meta slash commands under .claude/commands
• links the Meta skills and profile docs under .claude/meta-mcp
• creates editable .claude/meta-mcp/site-profiles.local.json and .claude/meta-mcp/BUSINESS_RULES.local.md if they do not exist
• appends a small managed Meta section to the target CLAUDE.md

If you are using the published package instead of a clone:

npx -y @edvintoome/meta-mcp install-claude --project /absolute/path/to/project

After installation:

1. Edit .claude/meta-mcp/site-profiles.local.json
2. Edit .claude/meta-mcp/BUSINESS_RULES.local.md
3. Make sure the shell that launches Claude Code has META_ACCESS_TOKEN
4. Open the project in Claude Code and run /meta-ads-builder

🔧 Configuration Guide

Step 1: Get Meta Access Token

1. Create a Meta App at developers.facebook.com
2. Add Marketing API product
3. Generate an access token with ads_read and ads_management permissions
4. If your app requires appsecret_proof, set META_APP_SECRET (see below)
5. (Optional) Set up OAuth for automatic token refresh

Step 2: Configure Claude Desktop

Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

If the file doesn't exist, create it with the following content:

Basic Configuration (Token-based):

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@edvintoome/meta-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

Advanced Configuration (with OAuth + appsecret_proof):

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@edvintoome/meta-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here",
        "META_APP_ID": "your_app_id",
        "META_APP_SECRET": "your_app_secret",
        "META_AUTO_REFRESH": "true",
        "META_BUSINESS_ID": "your_business_id"
      }
    }
  }
}

Local Development Configuration:

If you've cloned the repository locally:

{
  "mcpServers": {
    "meta-ads": {
      "command": "node",
      "args": ["/absolute/path/to/meta-mcp/build/index.js"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

Codex Local Configuration:

Use the bundled example in examples/codex_config.toml or add this to ~/.codex/config.toml:

[mcp_servers.meta]
command = "/absolute/path/to/meta-mcp/node_modules/.bin/tsx"
args = ["/absolute/path/to/meta-mcp/src/index.ts"]
enabled = true

[mcp_servers.meta.env]
META_ACCESS_TOKEN = "your_meta_access_token_here"
META_APP_ID = "your_app_id_optional"
META_APP_SECRET = "your_app_secret_optional"
META_BUSINESS_ID = "your_business_id_optional"
META_AUTO_REFRESH = "true"

The server name should stay meta if you want the bundled skill to work without edits, because the skill calls mcp__meta__... tools directly.

Step 3: Configure for Cursor

Cursor uses the same MCP configuration as Claude Desktop. Add the configuration to your Cursor settings:

1. Open Cursor Settings
2. Go to "Extensions" > "Claude"
3. Add the MCP server configuration in the JSON settings

Step 4: Restart Your Client

• Claude Desktop: Completely quit and restart the application
• Cursor: Restart the IDE

Step 5: Verify Setup

# Verify from your MCP client by calling the health_check tool

🔍 Troubleshooting

Common Issues

1. "Command not found" or "npx" errors

# Install Node.js if not installed
# macOS: brew install node
# Windows: Download from nodejs.org
# Linux: Use your package manager

# Verify installation
node --version
npm --version
npx --version

2. Permission errors

# Fix npm permissions (macOS/Linux)
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# Or install without sudo
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

3. Meta API connection issues

# Test your token manually
curl -G \
  -d "access_token=YOUR_ACCESS_TOKEN" \
  "https://graph.facebook.com/v23.0/me/adaccounts"

If the response says appsecret_proof is required, set META_APP_SECRET in your MCP server environment.

4. Check Claude Desktop logs

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

# macOS/Linux - View logs
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows - View logs
type "%APPDATA%\Claude\logs\mcp*.log"

5. Test the server manually

# Test the MCP server directly
npx -y @edvintoome/meta-mcp

# Or if installed locally
node build/index.js

Debug Mode

Enable debug logging by adding to your environment:

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "@edvintoome/meta-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here",
        "META_MCP_DEBUG": "1",
        "NODE_ENV": "development"
      }
    }
  }
}

🌐 Web Deployment (Vercel)

For web applications, you can deploy this server to Vercel and expose an HTTP MCP endpoint:

Configuration:

1. Deploy to Vercel
2. Set environment variables in Vercel dashboard
3. Configure OAuth app in Meta Developer Console
4. Use the web endpoint: https://your-project.vercel.app/api/mcp

MCP Client Configuration for Web:

{
  "mcpServers": {
    "meta-ads-remote": {
      "url": "https://your-project.vercel.app/api/mcp",
      "headers": {
        "Authorization": "Bearer your_session_token"
      }
    }
  }
}

Note: You need to authenticate against your deployment to get a session token.

Remote MCP Configuration (mcp-remote)

For Vercel deployments, use mcp-remote to bridge HTTP to stdio:

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-project.vercel.app/api/mcp",
        "--header",
        "Authorization:${META_AUTH_HEADER}"
      ],
      "env": {
        "META_AUTH_HEADER": "Bearer your_session_token_here"
      }
    }
  }
}

🛠️ Available Tools

This MCP server provides 25 comprehensive tools across all major Meta advertising categories:

📊 Analytics & Insights (3 tools)

• get_insights - Get detailed performance metrics (impressions, clicks, ROAS, CTR, CPC, etc.)
• compare_performance - Side-by-side performance comparison of multiple campaigns/ads
• export_insights - Export performance data in JSON or CSV formats

📈 Campaign Management (4 tools)

• create_campaign - Create new advertising campaigns with full configuration (includes special_ad_categories)
• update_campaign - Modify existing campaigns (name, budget, status, etc.)
• pause_campaign - Pause active campaigns
• resume_campaign - Resume/activate paused campaigns

🎯 Ad Set Management (2 tools)

• create_ad_set - Create ad sets with detailed targeting, budgets, and optimization goals
• list_ad_sets - List and filter ad sets within campaigns

📱 Ad Management (2 tools)

• create_ad - Create individual ads within ad sets using creative IDs
• list_ads - List and filter ads by ad set, campaign, or account

👥 Audience Management (4 tools)

• list_audiences - List all custom audiences for an account
• create_custom_audience - Create custom audiences from various sources
• create_lookalike_audience - Generate lookalike audiences from source audiences
• get_audience_info - Get detailed information about specific audiences

🎨 Creative Management (2 tools)

• list_ad_creatives - List all ad creatives for an account
• create_ad_creative - Create new ad creatives with rich specifications (supports external image URLs)

🔧 Account & Basic Tools (3 tools)

• health_check - Comprehensive authentication and server status check
• get_ad_accounts - List accessible Meta ad accounts
• get_campaigns - List campaigns with filtering options

🔐 Authentication Tools (1 tool)

• get_token_info - Token validation and information retrieval

🩺 Diagnostic Tools (2 tools)

• diagnose_campaign_readiness - Check campaign status and identify ad set creation issues
• check_account_setup - Comprehensive account validation and setup verification

🛠️ Usage Examples

Test the Connection

Check the health of the Meta Marketing API server and authentication status

Analytics & Performance Insights

Get detailed performance insights for my Deal Draft campaign including impressions, clicks, ROAS, and CTR for the last 30 days

Compare the performance of my top 3 campaigns side-by-side for the last quarter

Export campaign performance data for all my campaigns last month in CSV format

Campaign Management

Create a new traffic campaign named "Holiday Sale 2024" with a $50 daily budget and OUTCOME_TRAFFIC objective

Update my existing campaign budget to $100 daily and change the name to "Black Friday Special"

Pause all campaigns that have a CPC above $2.00

Resume my paused "Summer Collection" campaign

Complete Campaign Setup (Campaign → Ad Set → Ads)

Create a complete "Test 3" campaign setup: 1) Create the campaign with OUTCOME_LEADS objective, 2) Create an ad set targeting US users aged 25-45 interested in entrepreneurship, 3) Create 4 different ads using my existing creatives

Create an ad set for my existing campaign targeting women aged 30-50 in major US cities with interests in business and personal development

Create a new ad in my ad set using creative ID 123456 and name it "Headline Test A"

Troubleshooting & Diagnostics

Diagnose my "Test 3" campaign to see if it's ready for ad set creation and identify any potential issues

Check my account setup to verify payment methods, business verification, and ad account permissions

Check why my ad set creation failed and get specific recommendations for my account setup

Audience Management

List all my custom audiences and show their sizes and status

Create a custom audience named "Website Visitors" from people who visited my site

Create a 5% lookalike audience based on my "High Value Customers" audience targeting the US

Get detailed information about my "Newsletter Subscribers" audience including health status

Creative Management

List all my ad creatives and show their performance data

Create a new ad creative for my holiday campaign with external image URL from my website and specific messaging

Account Management

Show me all my accessible Meta ad accounts with their currencies and time zones

Get my current access token information including permissions and expiration

📚 Resources Access

The server provides rich contextual data through MCP resources:

• meta://campaigns/{account_id} - Campaign overview
• meta://insights/account/{account_id} - Performance dashboard
• meta://audiences/{account_id} - Audience insights
• meta://audience-health/{account_id} - Audience health report

🔧 Environment Variables

Required

META_ACCESS_TOKEN=your_access_token_here

Optional

META_APP_ID=your_app_id                    # For OAuth
META_APP_SECRET=your_app_secret            # For OAuth
META_BUSINESS_ID=your_business_id          # For business-specific operations
META_API_VERSION=v23.0                     # API version (default: v23.0)
META_API_TIER=standard                     # 'development' or 'standard'
META_AUTO_REFRESH=true                     # Enable automatic token refresh
META_REFRESH_TOKEN=your_refresh_token      # For token refresh
META_MCP_REQUEST_TIMEOUT_MS=30000          # Request timeout in ms (0 to disable)
META_MCP_DEBUG=1                           # Enable verbose MetaApiClient debug logs

📖 Documentation

• All documentation is in this README (setup, configuration, and tools)
• Example Configuration - Sample configuration file

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude AI     │◄──►│ MCP Server       │◄──►│ Meta Marketing  │
│                 │    │                  │    │ API             │
│ - Natural       │    │ - Authentication │    │                 │
│   Language      │    │ - Rate Limiting  │    │ - Campaigns     │
│ - Tool Calls    │    │ - Error Handling │    │ - Analytics     │
│ - Resource      │    │ - Data Transform │    │ - Audiences     │
│   Access        │    │ - Pagination     │    │ - Creatives     │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Core Components

• Meta API Client: Handles authentication, rate limiting, and API communication
• Tool Handlers: 25 tools covering analytics, campaigns, ad sets, ads, audiences, creatives, and diagnostics
• Resource Providers: Contextual data access for AI understanding
• Error Management: Robust error handling with automatic retries
• Rate Limiter: Intelligent rate limiting with per-account tracking

🔒 Security & Best Practices

Token Security

• ✅ Environment variable configuration
• ✅ No token logging or exposure
• ✅ Automatic token validation
• ✅ Secure credential management

API Management

• ✅ Rate limit compliance
• ✅ Exponential backoff retries
• ✅ Request validation
• ✅ Error boundary protection

Data Privacy

• ✅ Meta data use policy compliance
• ✅ No persistent data storage
• ✅ Secure API communication
• ✅ Audit trail support

⚡ Performance

Rate Limits

• Development Tier: 60 API calls per 5 minutes
• Standard Tier: 9000 API calls per 5 minutes
• Automatic Management: Built-in rate limiting and retry logic

Optimization

• 🚀 Concurrent request processing
• 📦 Efficient pagination handling
• 🎯 Smart data caching
• ⚡ Minimal memory footprint

🧪 Testing

Run the test suite:

npm test

Test with example client:

npx tsx examples/client-example.ts

Health check:

# In Claude:
Check the health of the Meta Marketing API server

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes and add tests
4. Run the test suite: npm test
5. Submit a pull request

📄 License

MIT License - see LICENSE for details.

🆘 Support

• Documentation: See this README
• Issues: Open an issue on GitHub
• Meta API: Refer to Meta Marketing API docs
• MCP Protocol: See Model Context Protocol specification

Built for reliable Meta Marketing API automation with MCP.