Facebook Ads MCP server

The Facebook/Meta Ads MCP Server provides an interface to Meta Ads, enabling programmatic access to data and management features through the Model Context Protocol. This server allows AI assistants to interact directly with your Facebook advertising accounts.

Installation Options

Quick Setup Using the Installer

For the simplest setup experience:

1. Visit GoMarble's MCP page for the ready-to-use installer

Manual Setup

Prerequisites

• Python 3.10 or higher
• Required Python packages

Installation Steps

1. Create and activate a virtual environment (recommended):

   python3 -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Obtain Meta Access Token: You'll need a Meta User Access Token with necessary permissions (e.g., ads_read). You can generate this through the Meta Developer portal or let the server help create one for you.

Using the MCP Server

Integration with MCP Clients

To use this server with MCP-compatible clients like Cursor or Claude Desktop, add the following configuration:

{
  "mcpServers": {
    "fb-ads-mcp-server": {
      "command": "python",
      "args": [
        "/path/to/your/fb-ads-mcp-server/server.py",
        "--fb-token",
        "YOUR_META_ACCESS_TOKEN"
      ]
    }
  }
}

Remember to restart your MCP Client after updating the configuration.

Running the Server Directly

You can run the server directly for debugging purposes:

python server.py --fb-token YOUR_META_ACCESS_TOKEN

Available Tools

Account & Object Information

• list_ad_accounts: Lists all ad accounts linked to your token
• get_details_of_ad_account: Retrieves details for a specific ad account
• get_campaign_by_id: Gets information about a specific campaign
• get_adset_by_id: Retrieves details for a specific ad set
• get_ad_by_id: Gets information about a specific ad
• get_ad_creative_by_id: Retrieves creative details
• get_adsets_by_ids: Gets multiple ad sets by their IDs

Fetching Collections

• get_campaigns_by_adaccount: Lists campaigns within an ad account
• get_adsets_by_adaccount: Lists ad sets within an ad account
• get_ads_by_adaccount: Lists ads within an ad account
• get_adsets_by_campaign: Lists ad sets within a campaign
• get_ads_by_campaign: Lists ads within a campaign
• get_ads_by_adset: Lists ads within an ad set
• get_ad_creatives_by_ad_id: Gets creatives for a specific ad

Performance Data & Insights

• get_adaccount_insights: Retrieves performance metrics for an ad account
• get_campaign_insights: Retrieves performance metrics for a campaign
• get_adset_insights: Retrieves performance metrics for an ad set
• get_ad_insights: Retrieves performance metrics for an ad
• fetch_pagination_url: Fetches additional data from pagination URLs

Activity History

• get_activities_by_adaccount: Retrieves change history for an ad account
• get_activities_by_adset: Retrieves change history for an ad set

Community Support

Join the AI in Ads Slack community for help and updates.

Related Projects

You might also be interested in the Google Ads MCP Server for similar functionality with Google's advertising platform.

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 "fb-ads-mcp-server" '{"command":"python","args":["/path/to/your/fb-ads-mcp-server/server.py","--fb-token","YOUR_FACEBOOK_ACCESS_TOKEN"]}'

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": {
        "fb-ads-mcp-server": {
            "command": "python",
            "args": [
                "/path/to/your/fb-ads-mcp-server/server.py",
                "--fb-token",
                "YOUR_FACEBOOK_ACCESS_TOKEN"
            ]
        }
    }
}

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": {
        "fb-ads-mcp-server": {
            "command": "python",
            "args": [
                "/path/to/your/fb-ads-mcp-server/server.py",
                "--fb-token",
                "YOUR_FACEBOOK_ACCESS_TOKEN"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect