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

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

# Run health check to verify everything is working
npm run health-check

🔍 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 meta-ads-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", "meta-ads-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 - C