Meta Ads API MCP server

The Meta Ads MCP server enables AI models to access, analyze, and manage Meta advertising campaigns through a standardized interface. It allows language models to retrieve performance data, visualize ad creatives, and provide strategic insights for Facebook, Instagram, and other Meta platforms.

Installation

Quick Setup

1. Sign up for Pipeboard to authenticate with Meta
2. Get your Pipeboard token at pipeboard.co/api-tokens
3. Add this configuration to your MCP client:

"mcpServers": {
  "meta-ads": {
    "command": "uvx",
    "args": ["meta-ads-mcp"],
    "env": {
      "PIPEBOARD_API_TOKEN": "your_pipeboard_token"
    }
  }
}

Alternative Setup

If you prefer to use your own Meta Developer App instead of Pipeboard authentication, follow the custom Meta app instructions in the original documentation.

Configuration

Setting Environment Variables

Set your Pipeboard API token as an environment variable:

export PIPEBOARD_API_TOKEN=your_pipeboard_token

Integration with Claude Desktop or Cursor

For Claude Desktop, add the configuration to your claude_desktop_config.json:

"mcpServers": {
  "meta-ads": {
    "command": "uvx",
    "args": ["meta-ads-mcp"],
    "env": {
      "PIPEBOARD_API_TOKEN": "your_pipeboard_token"
    }
  }
}

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

Usage

Available Tools

The Meta Ads MCP provides numerous tools for managing Meta ad campaigns:

Account Management

• mcp_meta_ads_get_ad_accounts: Retrieve ad accounts accessible by a user

  Inputs:
  - access_token (optional): Will use cached token if not provided
  - user_id: Meta user ID or "me" for the current user
  - limit: Maximum number of accounts to return (default: 10)
  

• mcp_meta_ads_get_account_info: Get detailed information about a specific ad account

  Inputs:
  - access_token (optional): Will use cached token if not provided
  - account_id: Meta Ads account ID (format: act_XXXXXXXXX)
  

• mcp_meta_ads_get_account_pages: Get pages associated with a Meta Ads account

  Inputs:
  - access_token (optional): Will use cached token if not provided
  - account_id: Meta Ads account ID or "me" for current user's pages
  

Campaign Management

• mcp_meta_ads_get_campaigns: Retrieve campaigns for a Meta Ads account

  Inputs:
  - access_token (optional): Will use cached token if not provided
  - account_id: Meta Ads account ID
  - limit: Maximum number of campaigns to return (default: 10)
  - status_filter: Filter by status (empty for all, or 'ACTIVE', 'PAUSED', etc.)
  

• mcp_meta_ads_get_campaign_details: Get detailed information about a specific campaign

  Inputs:
  - access_token (optional): Will use cached token if not provided
  - campaign_id: Meta Ads campaign ID
  

• mcp_meta_ads_create_campaign: Create a new campaign

  Inputs:
  - access_token (optional): Will use cached token if not provided
  - account_id: Meta Ads account ID
  - name: Campaign name
  - objective: Campaign objective (AWARENESS, TRAFFIC, etc.)
  - status: Initial campaign status (default: PAUSED)
  - special_ad_categories: List of special ad categories if applicable
  - daily_budget/lifetime_budget: Budget in account currency (in cents)
  

Ad Set Management

• mcp_meta_ads_get_adsets: Get ad sets for a Meta Ads account
• mcp_meta_ads_get_adset_details: Get detailed information about a specific ad set
• mcp_meta_ads_create_adset: Create a new ad set
• mcp_meta_ads_update_adset: Update an ad set with new settings

Ad Management

• mcp_meta_ads_get_ads: Get ads for a Meta Ads account
• mcp_meta_ads_create_ad: Create a new ad with an existing creative
• mcp_meta_ads_get_ad_details: Get detailed information about a specific ad
• mcp_meta_ads_update_ad: Update an ad with new settings

Creative Management

• mcp_meta_ads_get_ad_creatives: Get creative details for a specific ad
• mcp_meta_ads_create_ad_creative: Create a new ad creative
• mcp_meta_ads_upload_ad_image: Upload an image to use in Meta Ads creatives
• mcp_meta_ads_get_ad_image: Get, download, and visualize a Meta ad image

Analytics

• mcp_meta_ads_get_insights: Get performance insights for a campaign, ad set, ad or account

  Inputs:
  - access_token (optional): Will use cached token if not provided
  - object_id: ID of the campaign, ad set, ad or account
  - time_range: Time range for insights (default: maximum)
  - breakdown: Optional breakdown dimension (e.g., age, gender, country)
  - level: Level of aggregation (ad, adset, campaign, account)
  

Budget Management

• mcp_meta-ads_create_budget_schedule: Create a budget schedule for a Meta Ads campaign

Troubleshooting

Authentication Issues

If you encounter authentication problems:

1. Verify your Pipeboard setup:

   • Check that PIPEBOARD_API_TOKEN is set correctly
   • Verify your token in the Pipeboard dashboard

2. When using an LLM interface:

   • Ensure the PIPEBOARD_API_TOKEN environment variable is set
   • Check that the callback server is running properly

API Errors

If you receive errors from the Meta API:

• Ensure the user has appropriate permissions on the ad accounts
• Check if there are rate limits or other restrictions
• Verify your Pipeboard token hasn't expired

Logs

Log files are stored in platform-specific locations:

• 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

Privacy and Security

The Meta Ads MCP securely stores tokens in platform-specific locations:

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

You do not need to provide your access token for each command; it will be automatically retrieved from the cache.

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.