📊 Meta Ads Analyzer

Ask Claude about your ad campaigns the way you'd ask a senior media buyer.

An MCP server that turns your Meta Ads data into a conversational analytics layer. Unlike other Meta Ads MCP tools that wrap the live API, this one stores your historical data locally and lets you query it with natural language.

Why this exists

Ads Manager gives you charts. But try answering:

• "Which creatives are fatigued right now?"
• "Where am I leaking spend below 1.5x ROAS?"
• "Is my audience decaying or is it a creative problem?"

You can't — not without exporting CSVs and building dashboards. This tool gives Claude direct access to your campaign data with built-in marketing intelligence, so you just ask.

Built-in intelligence

Tool	What it detects
Creative fatigue	Frequency > 3 + declining CTR = fatigued creative
Audience decay	Frequency < 2 + dropping CVR = exhausted audience
Spend leaks	>40% budget at <1.5x ROAS = wasted money
Retargeting cannibalization	Retargeting > 25% of spend = cannibalizing prospecting
Placement optimization	Which placements (Feed, Stories, Reels) deliver best ROI
Hourly patterns	Best/worst hours for your campaigns

Plus: campaign rankings, daily trends, demographic breakdowns, country-level ROI, device performance, and custom SQL.

Requirements

• Python 3.10+ on your machine
• Claude Pro or Max subscription — MCP servers only work with Claude Desktop, Claude Code, or Claude.ai (not ChatGPT, Gemini, or free Claude)
• Meta Ads account — to pull your own data (or try with included sample data, no account needed)

Works with any MCP-compatible client: Claude Desktop (Mac/Windows), Claude Code (terminal), Claude.ai (web), Cursor, Windsurf.

Quick start

Install

pip install meta-ads-analyzer

Add to Claude Desktop

Open your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json) and add:

{
  "mcpServers": {
    "meta-ads-analyzer": {
      "command": "python3",
      "args": ["-m", "meta_ads_analyzer"],
      "env": {
        "META_ADS_DB_PATH": "~/meta_ads_data.db"
      }
    }
  }
}

Restart Claude Desktop. Done.

Try with sample data (no Meta account needed)

git clone https://github.com/shibanshu12/meta-ads-analyzer.git
cd meta-ads-analyzer
pip install .
META_ADS_DB_PATH=./examples/sample_data.db python -m meta_ads_analyzer

Use with your own Meta Ads data

Step 1: Get your Meta API credentials

1. Go to Meta for Developers → create an app
2. Open Tools → Graph API Explorer
3. Generate an access token with ads_read permission
4. Find your ad account ID in Ads Manager URL — looks like act_123456789

Step 2: Pull your data

# Clone the repo
git clone https://github.com/shibanshu12/meta-ads-analyzer.git
cd meta-ads-analyzer

# Set your credentials
export META_ACCESS_TOKEN="paste-your-token-here"
export META_AD_ACCOUNT_ID="act_123456789"

# Pull last 90 days of data (first time)
python pipeline/meta_ads_puller.py --days 90

# This creates ~/meta_ads_data.db on your machine

Step 3: Install and connect to Claude

pip install meta-ads-analyzer

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "meta-ads-analyzer": {
      "command": "python3",
      "args": ["-m", "meta_ads_analyzer"],
      "env": {
        "META_ADS_DB_PATH": "~/meta_ads_data.db"
      }
    }
  }
}

Restart Claude Desktop. Ask: "Check my data health"

Step 4 (optional): Automate daily pulls

Fork this repo and set up GitHub Actions to pull fresh data every day — even when your laptop is off. See pipeline docs for setup.

---

Example queries

Once connected, just ask Claude:

"Check my data health"
"Which campaigns have creative fatigue right now?"
"Show me my biggest spend leaks"
"ROAS by placement for the last 14 days"
"Which demographics convert best?"
"Compare this week vs last week"
"What's my retargeting cannibalization rate?"
"Show hourly performance patterns"
"Run a custom query: SELECT campaign_name, SUM(spend) FROM insights_daily GROUP BY campaign_name"

All 15 tools

Performance

Tool	Description
get_performance_summary	Overall account metrics — spend, ROAS, CPA, trends
get_campaign_performance	Campaign rankings sorted by spend, ROAS, or CPA
get_daily_trend	Day-by-day spend and ROAS trend line
identify_spend_leaks	Campaigns/adsets burning budget below ROAS threshold
run_custom_query	Run any SELECT query against the database

Creative

Tool	Description
detect_creative_fatigue	Ads with high frequency + declining CTR
detect_audience_decay	Adsets with low frequency but dropping conversion rate
get_creative_performance	All creatives ranked by ROAS

Audience

Tool	Description
get_demographic_performance	Performance by age × gender
get_country_performance	Performance by country
detect_retargeting_cannibalization	Check if retargeting is eating prospecting budget

Placement & Device

Tool	Description
get_placement_performance	Feed vs Stories vs Reels vs Audience Network
get_device_performance	Mobile vs desktop vs tablet
get_hourly_performance	Performance by hour (for dayparting)

Diagnostics

Tool	Description
check_data_health	Database tables, date ranges, row counts, freshness
get_table_schema	Column definitions for any table
list_campaigns	All campaigns with IDs (for filtering other tools)

Automated data pipeline

This repo includes a GitHub Actions pipeline that pulls data from the Meta Marketing API daily — no local machine needed.

See pipeline setup docs for instructions.

How it compares

Feature	meta-ads-analyzer	pipeboard (510⭐)	gomarble (230⭐)
Campaign CRUD	❌	✅	✅
Live API access	❌	✅	✅
Historical analytics	✅	❌	❌
Creative fatigue detection	✅	❌	❌
Audience decay signals	✅	❌	❌
Spend leak identification	✅	❌	❌
Works offline	✅	❌	❌
Automated data pipeline	✅	❌	❌
Sample data for testing	✅	❌	❌

This is not a replacement for pipeboard or gomarble. They handle campaign management. This handles campaign analysis. Use them together.

Database schema

The server expects a SQLite database with these tables:

Table	Description
insights_daily	Daily metrics per ad (no breakdown)
insights_demographics	Metrics broken down by age + gender
insights_placement	Metrics by platform + position
insights_country	Metrics by country
insights_hourly	Metrics by hour of day (7 days only)
insights_device	Metrics by device type

Each table contains: campaign_id, campaign_name, adset_id, adset_name, ad_id, ad_name, date, spend, impressions, clicks, reach, purchases, purchase_value + breakdown columns.

Contributing

Contributions welcome. See open issues for ideas.

git clone https://github.com/shibanshu12/meta-ads-analyzer.git
cd meta-ads-analyzer
pip install -e .

License

MIT — use it however you want.

Built by

Shibanshu Jha — 7+ years in performance marketing, managed $100M+ in Meta ad spend across India, US, UK, and Germany. Built this to solve problems I face daily as a growth marketing leader.