Facebook Ads MCP Server

Unlock Deeper Facebook Ads Insights: Powered by AI & MCP

Stop Clicking, Start Asking. Connect your AI assistant (Cursor, Claude, etc.) directly to your Facebook Ads data with this powerful MCP Server.

Instantly get answers like:

• "Show me my top 5 campaigns by ROAS last month?"
• "Compare CTR for ad sets A vs. B over the last 7 days."
• "What was the total spend breakdown by age and gender for campaign 'Summer Sale'?"
• "Who paused ad set 'Ad Set - Leads Q3' yesterday?"

Why You Need This:

• AI-Powered Analysis: Query your ads data using natural language via your AI assistant.
• Deep Data Access: Go beyond basics – campaigns, ad sets, ads, creatives, insights, history.
• Granular Insights: Fetch performance with custom dates, breakdowns (age, platform, etc.), filters & attribution.
• Track Changes: See who changed what and when (get_activities_...).
• Easy Setup: Standard Python, quick to deploy.

Quick Start Guide:

1. Prerequisites: Python 3.10+, Facebook Access Token (ads_read permission).
2. Setup:
   • (Optional) Create Python virtual environment (python3 -m venv venv && source venv/bin/activate)
   • Install: pip install -r requirements.txt
3. Prepare Server:

   python server.py --fb-token YOUR_FACEBOOK_ACCESS_TOKEN
   

4. Connect AI Client: Add to MCP config (adjust paths):

   {
     "mcpServers": {
       "fb-ads-mcp-server": {
         "command": "/path/to/venv/bin/python", // Or just "python"
         "args": [ "/path/to/server.py", "--fb-token", "YOUR_TOKEN" ]
       }
     }
   }
   

5. Restart your AI client.

Example Interactions:

This server gives your AI tools to talk to the Facebook Ads API. Ask questions like:

• Get Objects:
  • "Get details for campaign 1234567890 using fields: name, objective, effective_status."
  • "Fetch ad creative 2384xxxxxxxxx and show its image_url and body."
• List Objects:
  • "List all ads in ad set 6123xxxxxxxxx with effective_status ACTIVE."
  • "Show me all campaigns in account act_987654321."
• Analyze Performance:
  • "What was the spend, impressions, and clicks for account act_987654321 last_30d?"
  • "Get insights for ad 6789xxxxxxxxx broken down by publisher_platform for the last 7 days."
  • "Fetch campaign insights for 1234567890 with time_increment monthly for the last year."
• Audit History:
  • "Show me the activity log for ad set 4455667788 using time_range since 2024-01-15 until 2024-01-16."
  • "What changes happened in account act_987654321 today?"
• (Behind the Scenes) Paginate: If results are large, the AI can use fetch_pagination_url to get the next page automatically or upon request.

(See readme.md or server.py docstrings for the full list of tools and their detailed parameters!)