Meta Ads Insights MCP Server

A Model Context Protocol (MCP) server for accessing Meta (Facebook) Ads insights data with built-in support for joining with HubSpot deal data.

Features

• Fetch ad insights with flexible filtering and breakdowns
• Campaign and ad set management
• Mobile placement tracking for revenue attribution
• Prepare ads data for joining with HubSpot deals
• Configurable access tokens via MCP configuration

Setup

1. Install dependencies:

npm install

2. Build the server:

npm run build

3. Configure Claude Desktop: Add the server configuration to your Claude Desktop config file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "meta-ads-insights": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"],
      "env": {
        "META_ACCESS_TOKEN": "your_meta_access_token_here",
        "META_AD_ACCOUNT_ID": "your_ad_account_id_without_act_prefix",
        "META_API_VERSION": "v19.0"
      }
    }
  }
}

4. Get your Meta Access Token:

   • Go to Meta for Developers
   • Create an app or use existing app
   • Generate a User Access Token with ads_read permission
   • For production, use a System User Access Token

5. Find your Ad Account ID:

   • Go to Meta Ads Manager
   • The account ID is in the URL: act_1234567890 (use just 1234567890)

Available Tools

get_ad_insights

Fetch ad performance data with breakdowns and filtering.

Example usage:

Get mobile ad performance for the last 30 days with placement breakdown

get_campaigns

List campaigns with filtering options.

get_adsets

List ad sets, optionally filtered by campaign.

prepare_hubspot_join

Prepare ads data for joining with HubSpot deals data using various strategies:

• date_range: Match deals created within attribution window
• utm_params: Match deals with UTM parameters
• conversion_tracking: Match deals with Facebook click IDs

Example workflow:

1. Get mobile placement ads data
2. Prepare for HubSpot join with date range strategy
3. Use the prepared data to query HubSpot for deals created within the attribution window
4. Analyze mobile ads → revenue correlation

Example Use Cases

Mobile Ads Revenue Attribution

1. Get ads insights with device_platform and placement breakdowns
2. Filter for mobile placements
3. Prepare data for HubSpot join with 7-day attribution window
4. Query HubSpot deals created in that timeframe
5. Calculate ROI from mobile ad spend to deal revenue

Campaign Performance Analysis

1. Get campaign insights for last 30 days
2. Break down by placement and device
3. Join with HubSpot deal data
4. Identify highest-converting campaign + placement combinations

Data Joining Strategy

The server provides a prepare_hubspot_join tool that:

• Adds join keys based on strategy (UTM params, date ranges, click IDs)
• Calculates attribution windows
• Flags mobile placements for filtering
• Provides HubSpot query suggestions

This allows you to connect ad performance data with actual revenue outcomes tracked in HubSpot.

Development

# Development mode with auto-rebuild
npm run dev

# Build only
npm run build

# Run built server
npm start

Troubleshooting

• Ensure your Meta access token has ads_read permission
• Verify the ad account ID is correct (without "act_" prefix)
• Check that the absolute path in claude_desktop_config.json is correct
• Restart Claude Desktop after configuration changes# meta-insights-mcp