Meta Ads MCP Server

This is a Model Context Protocol (MCP) server for interacting with the Meta Marketing API. It allows AI assistants to retrieve Meta Ads data through a standardized protocol.

Getting Started (Recommended)

The easiest way to use this MCP server is with NPX:

1. Add this configuration to your Claude Desktop or VS Code Claude settings:

   {
     "mcpServers": {
       "meta-ads-mcp": {
         "command": "npx",
         "args": [
           "mcp-meta-ads"
         ],
         "env": {
           "META_APP_ID": "your_app_id",
           "META_APP_SECRET": "your_app_secret",
           "META_ACCESS_TOKEN": "your_access_token",
           "DEFAULT_AD_ACCOUNT_ID": "your_ad_account_id"
         },
         "transportType": "stdio"
       }
     }
   }

2. That's it! Your AI assistant will now have access to your Meta Ads data.

For more detailed setup options, see NPX Usage Guide.

Usage Options

This server supports two usage modes:

1. NPX Mode: Run directly from npm without installing globally (recommended)
2. Local Mode: For direct use with Claude Desktop or VS Code Claude (uses stdio transport)

• See NPX Usage Guide for instructions on using with NPX (recommended)

Features

• Secure access to the Meta Marketing API with proper credential management
• Built-in tools for common marketing data retrieval tasks
• Automatic handling of Ad Account ID formatting
• Compatible with Claude Desktop and VS Code Claude

Available Tools

1. list_campaigns - Fetches a list of campaigns from a Meta Ads account
2. get_campaign_insights - Retrieves performance metrics for ad campaigns

Setup Instructions

1. Install Dependencies

npm install

2. Environment Configuration

Create a .env file in the root directory with the following content:

# Meta Marketing API Credentials
META_APP_ID=your_app_id
META_APP_SECRET=your_app_secret
META_ACCESS_TOKEN=your_access_token

# Default Ad Account ID
# The 'act_' prefix will be added automatically if not present
DEFAULT_AD_ACCOUNT_ID=your_ad_account_id

3. Configuration for Claude Desktop

Add the server configuration to your Claude Desktop config file (claude_desktop_config.json):

{
  "mcpServers": {
    "meta-ads-mcp": {
      "disabled": false,
      "timeout": 60,
      "command": "node",
      "args": [
        "path/to/mcp-meta-ads/mcp_server.js"
      ],
      "env": {
        "META_APP_ID": "your_app_id",
        "META_APP_SECRET": "your_app_secret",
        "META_ACCESS_TOKEN": "your_access_token",
        "DEFAULT_AD_ACCOUNT_ID": "your_ad_account_id"
      },
      "transportType": "stdio",
      "autoApprove": [
        "list_campaigns",
        "get_campaign_insights"
      ]
    }
  }
}

4. Configuration for VS Code Claude

Add the server configuration to your VS Code Claude settings file (cline_mcp_settings.json):

{
  "mcpServers": {
    "meta-ads-mcp": {
      "disabled": false,
      "timeout": 60,
      "command": "node",
      "args": [
        "path/to/mcp-meta-ads/mcp_server.js"
      ],
      "env": {
        "META_APP_ID": "your_app_id",
        "META_APP_SECRET": "your_app_secret",
        "META_ACCESS_TOKEN": "your_access_token",
        "DEFAULT_AD_ACCOUNT_ID": "your_ad_account_id"
      },
      "transportType": "stdio",
      "autoApprove": [
        "list_campaigns",
        "get_campaign_insights"
      ]
    }
  }
}

Note: The Ad Account ID can be provided with or without the 'act_' prefix. The server will automatically add the prefix if it's missing.

Running the Server

Start the server using:

npm start

Usage Examples

List Campaigns

This tool retrieves a list of campaigns from your Meta Ads account.

Parameters:

• ad_account_id (optional) - The ad account ID to use. If not provided, uses the default.
• campaign_statuses (optional) - Comma-separated list of statuses (e.g., "ACTIVE,PAUSED").

Example:

list_campaigns({campaign_statuses: "ACTIVE"})

Get Campaign Insights

This tool retrieves performance metrics for campaigns.

Parameters:

• ad_account_id (optional) - The ad account ID to use.
• campaign_ids (optional) - Comma-separated list of campaign IDs.
• metrics (optional) - Comma-separated list of metrics to retrieve (e.g., "spend,impressions,clicks").
• date_preset (optional) - Time period for the data (e.g., "last_7d", "last_30d").

Example:

get_campaign_insights({date_preset: "last_14d", metrics: "spend,impressions,clicks,ctr"})

Troubleshooting

Error: Invalid response format

If you encounter errors about invalid response format, make sure your server is returning responses in the correct MCP format:

return { 
  content: [
    {
      type: "text",
      text: JSON.stringify(yourData, null, 2)
    }
  ] 
};

Ad Account ID Issues

The server supports both formats for Ad Account IDs:

• With 'act_' prefix (e.g., "act_123456789")
• Without prefix (e.g., "123456789")

If you're having issues, check that your Ad Account ID is correct and that the server is properly formatting it.

License

ISC