Meta Ads MCP Server

An MCP (Model Context Protocol) server that connects Claude Desktop to the Meta Marketing API. Manage your Facebook & Instagram ad campaigns, read performance analytics, create campaigns, and get automated reports — all through natural conversation with Claude.

What You Can Do

Read Analytics: Campaign, ad set, and ad-level performance metrics
Create Campaigns: Full campaign → ad set → ad creation workflow
Manage Campaigns: Pause/activate campaigns, update budgets
Audience Insights: Performance breakdowns by age, gender, country, platform
Automated Reports: Weekly performance reports with recommendations
Ad Copy: Generate and push ad creatives directly to Meta

Prerequisites

1. Meta Developer Account & App

Go to Meta for Developers
Create a new app → Select "Other" → "Business" type
Add the Marketing API product to your app
Go to App Settings → Basic and note your App ID and App Secret

2. Access Token

For development/testing:

Go to Graph API Explorer
Select your app
Click "Generate Access Token"
Add permissions: ads_management, ads_read, pages_read_engagement
Copy the token

For production (long-lived token):

Exchange short-lived token for a long-lived one:

curl -X GET "https://graph.facebook.com/v21.0/oauth/access_token?grant_type=fb_exchange_token&client_id=YOUR_APP_ID&client_secret=YOUR_APP_SECRET&fb_exchange_token=YOUR_SHORT_TOKEN"

3. Ad Account ID

Find your Ad Account ID:

Go to Ads Manager
Look at the URL: act_XXXXXXXXXX is your account ID
Or go to Business Settings → Ad Accounts

4. Add Ad Account to App

Important step (often missed):

In your Meta app settings, go to Advanced Settings
Under Advertising Accounts, add your Ad Account ID
Make sure the email on your developer account is added to the Business Manager

Installation

Using uv (recommended)

# Clone/download the project
cd meta-ads-mcp

# Create virtual environment and install
uv venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows

uv pip install -e .

Using pip

cd meta-ads-mcp
pip install -e .

Configuration

1. Set Environment Variables

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

META_APP_ID=123456789
META_APP_SECRET=abc123def456
META_ACCESS_TOKEN=EAAxxxxxxx...
META_AD_ACCOUNT_ID=act_123456789

2. Configure Claude Desktop

Edit your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "meta-ads": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/meta-ads-mcp",
        "run",
        "meta-ads-mcp"
      ],
      "env": {
        "META_APP_ID": "your_app_id",
        "META_APP_SECRET": "your_app_secret",
        "META_ACCESS_TOKEN": "your_access_token",
        "META_AD_ACCOUNT_ID": "act_your_account_id"
      }
    }
  }
}

Alternative (if using pip install):

{
  "mcpServers": {
    "meta-ads": {
      "command": "meta-ads-mcp",
      "env": {
        "META_APP_ID": "your_app_id",
        "META_APP_SECRET": "your_app_secret",
        "META_ACCESS_TOKEN": "your_access_token",
        "META_AD_ACCOUNT_ID": "act_your_account_id"
      }
    }
  }
}

Restart Claude Desktop

Usage Examples

Check Campaign Performance

"Show me how my Meta campaigns performed last week" "Which campaign has the best ROAS in the last 30 days?" "Break down my top campaign by age group"

Create Campaigns

"Create a new traffic campaign for Kibbar targeting developers in the US and India, $20/day budget" "Set up an ad with this copy: [your copy] pointing to kibbar.com"

Manage Campaigns

"Pause the campaign called 'Summer Sale'" "Increase the daily budget on my best performing ad set to $50"

Get Reports

"Generate a weekly performance report with audience breakdowns" "Compare this week vs last week performance"

Optimize

"Analyze my campaigns and tell me where I'm wasting money" "Which ad sets should I increase budget on based on CPA?"

Available Tools

| Tool | Description | |------|-------------| | get_campaign_performance | Campaign-level metrics with flexible date ranges | | get_adset_performance | Ad set breakdown within a campaign | | get_ad_performance | Individual ad-level performance data | | list_campaigns | List all campaigns with status filtering | | create_campaign | Create new campaigns | | create_adset | Create ad sets with targeting | | create_ad | Create ads with creative content | | update_status | Pause/activate/archive any ad object | | update_budget | Adjust budgets on campaigns or ad sets | | generate_performance_report | Comprehensive report with daily breakdowns | | get_audience_breakdown | Audience insights by demographics/platform | | upload_ad_image | Upload images for ad creatives |

Available Prompts

| Prompt | Description | |--------|-------------| | analyze_campaign_performance | Deep analysis with optimization suggestions | | create_campaign_workflow | Guided campaign creation step-by-step | | weekly_report | Comprehensive weekly performance report |

Security Notes

Never commit your .env file or access tokens
Use long-lived tokens for production but rotate them regularly
The server creates campaigns in PAUSED status by default (safe to review before spending)
All write operations require explicit parameters — Claude won't accidentally modify things

Troubleshooting

"Missing Meta API credentials" → Check that all 4 environment variables are set in Claude Desktop config

"Invalid OAuth access token" → Your token expired. Generate a new one from Graph API Explorer

"Ad account not found" → Ensure your account ID starts with act_ and is added to your app in Advanced Settings

"Permission denied" → Check that your token has ads_management and ads_read permissions

License

MIT

MCP Servers