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

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:

If your app requires appsecret_proof, add META_APP_SECRET:

3) Restart your client

• Claude Desktop: quit and reopen

• Cursor: restart the IDE

4) Verify

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

Option 2: From Source

Option 3: Automated Setup (Easiest)

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

Advanced Configuration (with OAuth + appsecret_proof):

Local Development Configuration:

If you've cloned the repository locally:

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

🔍 Troubleshooting

Common Issues

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

2. Permission errors

3. Meta API connection issues

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

5. Test the server manually

Debug Mode

Enable debug logging by adding to your environment:

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

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:

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

Analytics & Performance Insights

Campaign Management

Complete Campaign Setup (Campaign → Ad Set → Ads)

Troubleshooting & Diagnostics

Audience Management

Creative Management

Account Management

📚 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

Optional

📖 Documentation

• All documentation is in this README (setup, configuration, and tools)

• Example Configuration - Sample configuration file

🏗️ Architecture

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:

Test with example client:

Health check:

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