Meta Marketing API MCP Server

Meta Marketing API MCP Server

A comprehensive Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Facebook/Instagram advertising data through the Meta Marketing API. This server provides full campaign lifecycle management, analytics, audience targeting, and creative optimization capabilities.

⚡ Quick Start

1) Install

npm install -g meta-ads-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", "meta-ads-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", "meta-ads-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

npm run health-check

🚀 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 meta-ads-mcp

Option 2: From Source

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

Option 3: Automated Setup (Easiest)

# Clone the repository first
git clone https://github.com/wipsoft/meta-mcp.git
cd meta-ads-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

🔧 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", "meta-ads-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

Advanced Configuration (with OAuth + appsecret_proof):

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": ["-y", "meta-ads-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-ads-mcp/build/index.js"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token_here"
      }