Meta Ads API MCP server

Meta Ads MCP server provides a standardized interface for AI models to interact with Meta Ads API, allowing Large Language Models (LLMs) to retrieve performance data, analyze ad campaigns, and deliver strategic insights for Facebook, Instagram, and other Meta advertising platforms.

Installation

Using uv (recommended)

You can run meta-ads-mcp directly without installation using uvx:

# Run with Meta authentication
uvx meta-ads-mcp --app-id YOUR_META_ADS_APP_ID

To install the package:

uv pip install meta-ads-mcp

If you're working with the repository:

# From the repository root
uv pip install -e .

Using pip

Alternatively, install using pip:

pip install meta-ads-mcp

After installation, run it with:

# Run with Meta authentication
python -m meta_ads_mcp --app-id YOUR_META_ADS_APP_ID

Configuration

Create a Meta Developer App (Required)

Before using the MCP server:

1. Go to Meta for Developers and create a new app
2. Choose the "Consumer" app type
3. Add the "Marketing API" product to your app
4. Configure your app's OAuth redirect URI to include http://localhost:8888/callback
5. Note your App ID (Client ID) for use with the MCP

Usage with Cursor or Claude Desktop

For Claude Desktop, add to your claude_desktop_config.json:

"mcpServers": {
  "meta-ads": {
    "command": "uvx",
    "args": ["meta-ads-mcp", "--app-id", "YOUR_META_ADS_APP_ID"]
  }
}

For Cursor, add to ~/.cursor/mcp.json with the same format.

Available MCP Tools

Account Management

• mcp_meta_ads_get_ad_accounts: Get accessible ad accounts
• mcp_meta_ads_get_account_info: Get detailed information about a specific ad account

Campaign Management

• mcp_meta_ads_get_campaigns: Retrieve campaigns with optional filtering
• mcp_meta_ads_get_campaign_details: Get detailed information about a specific campaign
• mcp_meta_ads_create_campaign: Create a new campaign

Ad Set Management

• mcp_meta_ads_get_adsets: Get ad sets with optional campaign filtering
• mcp_meta_ads_get_adset_details: Get detailed information about a specific ad set
• mcp_meta_ads_update_adset: Update an ad set with new settings

Ad Management

• mcp_meta_ads_get_ads: Get ads with optional filtering
• mcp_meta_ads_get_ad_details: Get detailed information about a specific ad
• mcp_meta_ads_get_ad_creatives: Get creative details for a specific ad
• mcp_meta_ads_get_ad_image: Visualize a Meta ad image
• mcp_meta_ads_update_ad: Update an ad with new settings

Insights and Analysis

• mcp_meta_ads_get_insights: Get performance metrics for campaigns, ad sets, or ads

Authentication and Utilities

• mcp_meta_ads_get_login_link: Get a clickable login link for authentication
• mcp_meta_ads_debug_image_download: Debug image download issues

Authentication

Meta Ads MCP uses OAuth 2.0 authentication flow:

1. A local callback server starts on your machine
2. A browser window opens for Meta authentication
3. You authorize the app
4. The browser redirects to the local server to extract and store the token securely

Troubleshooting and Logging

Log Location

Logs are stored at:

• macOS: ~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log
• Windows: %APPDATA%\meta-ads-mcp\meta_ads_debug.log
• Linux: ~/.config/meta-ads-mcp/meta_ads_debug.log

Common Issues

Authentication Issues

If you see (#200) Provide valid app ID, check:

• Your Meta Developer App setup
• That you're passing the correct App ID:

  export META_APP_ID=your_app_id
  # or
  meta-ads-mcp --app-id your_app_id
  

API Errors

For Meta API errors:

1. Verify your app has the Marketing API product
2. Check user permissions on ad accounts
3. Look for rate limits or restrictions

Running with Different App IDs

# Using environment variable
export META_APP_ID=your_app_id
uvx meta-ads-mcp

# Or using command line argument
uvx meta-ads-mcp --app-id=your_app_id

Privacy and Security

1. Tokens are cached securely in platform-specific locations
2. Access tokens are automatically retrieved from cache
3. You can set META_APP_ID as an environment variable
4. For direct token usage (e.g., in CI/CD):

   export META_ACCESS_TOKEN=your_access_token
   uvx meta-ads-mcp
   

Testing Your Setup

CLI Testing

python test_meta_ads_auth.py --app-id YOUR_APP_ID

Force a new authentication:

python test_meta_ads_auth.py --app-id YOUR_APP_ID --force-login

LLM Interface Testing

With an LLM interface (like Claude):

1. Test authentication with mcp_meta_ads_get_login_link
2. Verify account access with mcp_meta_ads_get_ad_accounts
3. Check account details with mcp_meta_ads_get_account_info

Checking Version

import meta_ads_mcp
print(meta_ads_mcp.__version__)

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.