Meta Ads Insights Macp
About
A Model Context Protocol (MCP) server for accessing Meta (Facebook) Ads insights data with built-in support for joining with HubSpot deal data.
Details
- Author
- ncklrs
- Downloads
- 342
- Categories
- Search
Jump to
- 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
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Meta Ads Insights MacpCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install dependencies with npm install, build with npm run build, then configure Claude Desktop by adding the server to claude_desktop_config.json with environment variables for META_ACCESS_TOKEN, META_AD_ACCOUNT_ID, and META_API_VERSION. After configuration, invoke tools like get_ad_insights, get_campaigns, get_adsets, or prepare_hubspot_join via natural language prompts in Claude.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"meta ads insights macp": {
"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"
}
}
}
}
}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"
}
}
}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
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
