Meta Ads API MCP server for AI agents

Meta Ads MCP is a tool that enables AI models to interact with Meta's advertising platforms through the Model Context Protocol (MCP). It allows AI assistants to retrieve performance data, analyze ad creatives, and provide strategic insights for Facebook, Instagram, and other Meta advertising campaigns.

Installation Options

Remote MCP (Recommended for Marketers)

The easiest way to get started is by using the remote MCP service:

For Claude Pro/Max Users

Go to claude.ai/settings/integrations (requires Claude Pro or Max)
Click "Add Integration" and enter:
- Name: "Pipeboard Meta Ads" (or any name you prefer)
- Integration URL: https://mcp.pipeboard.co/meta-ads-mcp
Click "Connect" next to the integration and follow the prompts to:
- Login to Pipeboard
- Connect your Facebook Ads account

For Cursor Users

Add the following to your ~/.cursor/mcp.json file:

{
  "mcpServers": {
    "meta-ads-remote": {
      "url": "https://mcp.pipeboard.co/meta-ads-mcp"
    }
  }
}

Once you enable the remote MCP, click on "Needs login" to complete the login process.

For Other MCP Clients

Use the Remote MCP URL: https://mcp.pipeboard.co/meta-ads-mcp

Local Installation (Technical Users Only)

If you need to run Meta Ads MCP locally:

# Install via uvx (recommended)
uvx meta-ads-mcp

# Set your Pipeboard token
export PIPEBOARD_API_TOKEN=your_pipeboard_token

Usage Examples

Available Tools

The Meta Ads MCP provides numerous tools for interacting with Meta's advertising platform:

Account Management

# Get all available ad accounts
mcp_meta_ads_get_ad_accounts(user_id="me", limit=10)

# Get detailed account information
mcp_meta_ads_get_account_info(account_id="act_123456789")

# Get pages associated with an account
mcp_meta_ads_get_account_pages(account_id="act_123456789")

Campaign Management

# List campaigns in an account
mcp_meta_ads_get_campaigns(account_id="act_123456789", limit=5, status_filter="ACTIVE")

# Get campaign details
mcp_meta_ads_get_campaign_details(campaign_id="23848711234560")

# Create a new campaign
mcp_meta_ads_create_campaign(
    account_id="act_123456789",
    name="2025 - Bedroom Furniture - Awareness",
    objective="OUTCOME_AWARENESS",
    status="PAUSED",
    special_ad_categories=[],
    daily_budget=10000,
    bid_strategy="LOWEST_COST_WITHOUT_CAP"
)

Ad Set Management

# Get ad sets in a campaign
mcp_meta_ads_get_adsets(account_id="act_123456789", campaign_id="23848711234560")

# Get ad set details
mcp_meta_ads_get_adset_details(adset_id="23848711234561")

# Update an ad set
mcp_meta_ads_update_adset(
    adset_id="23848711234561",
    status="ACTIVE",
    bid_amount=500
)

Ad Management

# Get ads in an ad set
mcp_meta_ads_get_ads(account_id="act_123456789", adset_id="23848711234561")

# Get ad details
mcp_meta_ads_get_ad_details(ad_id="23848711234562")

# Get ad creatives
mcp_meta_ads_get_ad_creatives(ad_id="23848711234562")

# Get and visualize an ad image
mcp_meta_ads_get_ad_image(ad_id="23848711234562")

# Update an ad
mcp_meta_ads_update_ad(
    ad_id="23848711234562",
    status="ACTIVE",
    bid_amount=300
)

Creating Ads

# Upload an image for an ad
image_response = mcp_meta_ads_upload_ad_image(
    account_id="act_123456789",
    image_path="/path/to/image.jpg",
    name="Product Image"
)

# Create an ad creative
creative_response = mcp_meta_ads_create_ad_creative(
    account_id="act_123456789",
    name="Summer Sale Creative",
    image_hash=image_response["images"]["image.jpg"]["hash"],
    page_id="123456789",
    link_url="https://example.com/sale",
    message="Check out our summer sale with 50% off all items!",
    headline="Summer Sale - 50% Off Everything",
    description="Limited time offer",
    call_to_action_type="SHOP_NOW"
)

# Create an ad using the creative
mcp_meta_ads_create_ad(
    account_id="act_123456789",
    name="Summer Sale Ad",
    adset_id="23848711234561",
    creative_id=creative_response["id"],
    status="PAUSED"
)

Performance Analysis

# Get performance insights for a campaign
mcp_meta_ads_get_insights(
    object_id="23848711234560",
    time_range="last_30_days",
    level="campaign"
)

# Get insights with breakdowns
mcp_meta_ads_get_insights(
    object_id="23848711234560",
    time_range="last_30_days",
    breakdown="age",
    level="ad"
)

Targeting Tools

# Search for interests
mcp_meta_ads_search_interests(query="basketball", limit=10)

# Get interest suggestions
mcp_meta_ads_get_interest_suggestions(interest_list=["Basketball", "Soccer"], limit=10)

# Validate interests
mcp_meta_ads_validate_interests(interest_list=["Japan", "Basketball"])

# Search for behaviors
mcp_meta_ads_search_behaviors(limit=10)

# Search for demographic targeting options
mcp_meta_ads_search_demographics(demographic_class="life_events", limit=10)

# Search for geographic locations
mcp_meta_ads_search_geo_locations(query="New York", location_types=["city", "region"])

Troubleshooting

If you encounter issues with the local installation, consider using the Remote MCP service instead for a simpler setup experience.

For authentication issues:

Use the mcp_meta_ads_get_login_link tool to get a fresh authentication link
Follow the link to complete the authentication process
Try your operation again

For more detailed troubleshooting assistance, visit pipeboard.co or join the Discord community at discord.gg/YNjF7gUb5h.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "meta-ads-remote" '{"command":"npx","args":["mcp-remote","https://mcp.pipeboard.co/meta-ads-mcp"]}'

See the official Claude Code MCP documentation for more details.

For 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 > Tools & Integrations and click "New MCP Server".

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

{
    "mcpServers": {
        "meta-ads-remote": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.pipeboard.co/meta-ads-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 explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "meta-ads-remote": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.pipeboard.co/meta-ads-mcp"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect