datagekko/facebook-ads-mcp

Facebook Ads MCP Server

A Claude MCP (Model Context Protocol) server that connects Claude to Facebook Ads, enabling AI-powered marketing analytics, performance tracking, and automated reporting.

Features

✅ Direct Facebook Ads Integration

• Connects directly to your Facebook Ads account via Marketing API
• Pulls all performance data automatically
• Real-time access to campaigns, ad sets, and ads

✅ Advanced Analytics & Metrics

• Calculates ROAS, CPA, conversion rates on demand
• Performance scoring (Quality Score, Efficiency Score)
• Trend analysis and week-over-week comparisons
• Video engagement metrics

✅ Intelligent Reporting

• Generates beautiful, comprehensive reports
• Multiple report types: Overview, Detailed Analysis, ROI Analysis, Trend Analysis
• Interactive charts and visualizations in markdown format
• Custom date ranges and filtering

✅ Built for Claude

• Seamless integration with Claude via MCP
• Natural language queries about your ad performance
• AI-powered insights and recommendations

Quick Start

1. Installation

# Clone and install
git clone <your-repo>
cd facebook-ads-mcp
npm install

2. Facebook App Setup

1. Go to Facebook Developers
2. Create a new app or use existing one
3. Add "Marketing API" product
4. Get your App ID, App Secret, and generate an Access Token
5. Find your Ad Account ID in Facebook Ads Manager (Settings > Account Settings)

3. Environment Configuration

Create a .env file:

# Required
FB_ACCESS_TOKEN=your_facebook_access_token
FB_ACCOUNT_ID=act_1234567890  # Your ad account ID (with 'act_' prefix)

# Optional (for enhanced security)
FB_APP_ID=your_app_id
FB_APP_SECRET=your_app_secret

4. Build and Run

# Build the project
npm run build

# Start the MCP server
npm start

5. Configure Claude

Add this to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "facebook-ads": {
      "command": "node",
      "args": ["/path/to/facebook-ads-mcp/dist/index.js"],
      "env": {
        "FB_ACCESS_TOKEN": "your_facebook_access_token",
        "FB_ACCOUNT_ID": "act_1234567890"
      }
    }
  }
}

Available Tools

📊 Data Access Tools

• get_account_info - Get Facebook Ads account information
• get_campaigns - Retrieve campaigns with filtering options
• get_campaign_insights - Get detailed performance insights
• get_ad_sets - Retrieve ad sets for campaigns
• get_ads - Retrieve individual ads

📈 Analytics Tools

• calculate_metrics - Calculate ROAS, CPA, conversion rates, quality scores
• generate_performance_report - Create comprehensive reports with visualizations

Usage Examples

Once configured, you can ask Claude natural language questions:

Basic Queries

"Show me my Facebook Ads account information"
"Get all my active campaigns"
"What's the performance of my latest campaign?"

Advanced Analytics

"Calculate ROAS and conversion metrics for campaign ID 123456789"
"Generate a detailed ROI analysis for the last 30 days"
"Show me a trend analysis comparing this week to last week"

Reporting

"Create a campaign overview report with charts"
"Generate a detailed analysis report for my top performing campaign"
"Show me an ROI analysis with profitability breakdown"

Report Types

1. Campaign Overview

• Account summary and campaign list
• Top performing campaigns
• Status distribution charts
• Key metrics at a glance

2. Detailed Analysis

• In-depth metrics for individual campaigns
• Performance breakdowns by ad sets
• Engagement and video metrics
• Quality and efficiency scoring

3. ROI Analysis

• ROAS analysis and profitability
• Campaign rankings by performance
• Overall account profitability
• Cost per conversion analysis

4. Trend Analysis

• Week-over-week performance trends
• Historical data comparison
• Growth patterns and insights
• Trend visualizations

Metrics Calculated

Performance Metrics

• ROAS (Return on Ad Spend)
• CPA (Cost Per Acquisition)
• CTR (Click-Through Rate)
• CPM (Cost Per Mille)
• CPC (Cost Per Click)

Conversion Metrics

• Conversion Rate
• Cost Per Conversion
• Purchase Value
• Total Conversions

Engagement Metrics

• Likes, Comments, Shares, Saves
• Engagement Rate
• Video Completion Rates

Quality Scores

• Quality Score (based on CTR, engagement, conversion rate)
• Efficiency Score (based on ROAS, CPC, CPP)

Development

# Development mode with auto-reload
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint

# Build
npm run build

Architecture

src/
├── index.ts              # Main MCP server entry point
├── facebook-ads-api.ts   # Facebook Marketing API integration
├── metrics-calculator.ts # Performance metrics and calculations
└── report-generator.ts   # Report generation and visualization

Security Best Practices

1. Environment Variables: Store sensitive data in environment variables, not in code
2. Access Token Security: Use short-lived tokens when possible
3. Permissions: Request only the minimum required permissions
4. Error Handling: Sensitive information is not exposed in error messages

Troubleshooting

Common Issues

1. "Missing required environment variables"

   • Ensure FB_ACCESS_TOKEN and FB_ACCOUNT_ID are set
   • Check that account ID has act_ prefix

2. "Failed to get account info"

   • Verify access token is valid and not expired
   • Check that token has ads_read permission
   • Ensure account ID is correct

3. "No insights data available"

   • Campaign might not have any activity in the specified date range
   • Try a different date range or campaign ID

Getting Help

1. Check Facebook's Marketing API documentation
2. Verify your app's permissions in Facebook Developer Console
3. Test API access using Facebook's Graph API Explorer

License

MIT License - see LICENSE file for details.