Skip to content
Back to search

meta-ads-analyzer

Meta Ads Analyzer skill + MCP server for Claude Code. Breakdown Effect, Learning Phase, and expert-level campaign diagnosis.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mathiaschu--meta-ads-analyzer/badge.svg)](/listings/mathiaschu--meta-ads-analyzer)

HTML

<a href="/listings/mathiaschu--meta-ads-analyzer"><img src="/api/listings/mathiaschu--meta-ads-analyzer/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install the Skill

Copy the `skill/` folder into your Claude Code project:

# From your Claude Code project root
mkdir -p .claude/skills/meta-ads-analyzer
cp -r skill/* .claude/skills/meta-ads-analyzer/

The skill is now active. Claude will automatically use it when you ask about Meta Ads analysis.

2. Set Up the MCP Server (optional, for live data)

The MCP server lets Claude pull live campaign data from Meta's API. Skip this if you only want to analyze exported data (CSV, screenshots).

a) Create a Meta App

1. Go to [developers.facebook.com](https://developers.facebook.com/apps/) 2. Create a new app (type: **Business**) 3. Add the **Marketing API** product 4. Note your **App ID** and **App Secret**

b) Generate an Access Token

1. Go to [Graph API Explorer](https://developers.facebook.com/tools/explorer/) 2. Select your app 3. Add permissions: `ads_read`, `ads_management`, `business_management` 4. Click **Generate Access Token** and authorize 5. Exchange for a long-lived token (60 days) using the setup script:

bash scripts/setup.sh

c) Configure Claude Code

Copy the MCP config template and add your credentials:

cp mcp/mcp.json.example .mcp.json

Edit `.mcp.json` and replace the placeholders with your actual token and app secret.

Then restart Claude Code for the MCP server to connect.

3. Verify

Ask Claude: **"Analyze my Meta Ads campaigns"** — it should connect to your ad account and start analyzing.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 121 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Meta Ads Analyzer for Claude Code
  2. A Claude Code skill + MCP server setup for expert-level Meta Ads campaign analysis. Includes the **Breakdown Effect** framework, Learning Phase diagnostics, and 9 reference documents from Meta's official documentation.
  3. ## What It Does
  4. When installed, Claude Code can:
  5. - Analyze campaign, ad set, and ad-level performance data
  6. - Identify root causes of performance issues using Meta's system mechanics
  7. - Explain the **Breakdown Effect** (why Meta allocates budget to seemingly "worse" segments)
  8. - Diagnose Learning Phase, Auction Overlap, Pacing, and Creative Fatigue issues
  9. - Generate structured analysis reports with actionable recommendations
  10. - Connect directly to Meta's API to pull live campaign data (via MCP)
  11. ## Components
  12. | Component | What it does |
  13. |---|---|
  14. | **Skill** (`skill/`) | Analysis framework with 9 reference docs that Claude loads as context |
  15. | **MCP Server** (`mcp/`) | Connects Claude Code to Meta's Marketing API for live data |
  16. | **Scripts** (`scripts/`) | Setup and token refresh helpers |
  17. ## Prerequisites
  18. - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
  19. - [Node.js](https://nodejs.org/) v18+
  20. - A Meta App with Marketing API access ([create one here](https://developers.facebook.com/apps/))
  21. ## Installation
  22. ### 1. Install the Skill
  23. Copy the `skill/` folder into your Claude Code project:
  24. ```bash
  25. # From your Claude Code project root
  26. mkdir -p .claude/skills/meta-ads-analyzer
  27. cp -r skill/* .claude/skills/meta-ads-analyzer/
  28. ```
  29. The skill is now active. Claude will automatically use it when you ask about Meta Ads analysis.
  30. ### 2. Set Up the MCP Server (optional, for live data)
  31. The MCP server lets Claude pull live campaign data from Meta's API. Skip this if you only want to analyze exported data (CSV, screenshots).
  32. #### a) Create a Meta App
  33. 1. Go to [developers.facebook.com](https://developers.facebook.com/apps/)
  34. 2. Create a new app (type: **Business**)
  35. 3. Add the **Marketing API** product
  36. 4. Note your **App ID** and **App Secret**
  37. #### b) Generate an Access Token
  38. 1. Go to [Graph API Explorer](https://developers.facebook.com/tools/explorer/)
  39. 2. Select your app
  40. 3. Add permissions: `ads_read`, `ads_management`, `business_management`
  41. 4. Click **Generate Access Token** and authorize
  42. 5. Exchange for a long-lived token (60 days) using the setup script:
  43. ```bash
  44. bash scripts/setup.sh
  45. ```
  46. #### c) Configure Claude Code
  47. Copy the MCP config template and add your credentials:
  48. ```bash
  49. cp mcp/mcp.json.example .mcp.json
  50. ```
  51. Edit `.mcp.json` and replace the placeholders with your actual token and app secret.
  52. Then restart Claude Code for the MCP server to connect.
  53. ### 3. Verify
  54. Ask Claude: **"Analyze my Meta Ads campaigns"** — it should connect to your ad account and start analyzing.
  55. ## Token Refresh
  56. Meta long-lived tokens expire after ~60 days. To refresh:
  57. ```bash
  58. bash scripts/refresh_token.sh
  59. ```
  60. If the token already expired, generate a new one from the [Graph API Explorer](https://developers.facebook.com/tools/explorer/) and run `scripts/setup.sh` again.
  61. ## Usage Examples
  62. Once installed, you can ask Claude things like:
  63. - "Analyze my campaigns from the last 7 days"
  64. - "Why is my CPA increasing on this campaign?"
  65. - "Compare performance across placements"
  66. - "Diagnose why this ad set is in Learning Limited"
  67. - "Export a full analysis report for [campaign name]"
  68. You can also paste CSV exports or screenshots from Meta Ads Manager — the skill works with any data format.
  69. ## What's in the Reference Docs
  70. | Document | Covers |
  71. |---|---|
  72. | `breakdown_effect.md` | Why Meta allocates budget to "expensive" segments |
  73. | `core_concepts.md` | Ad Auction, Pacing, Learning Phase overview |
  74. | `learning_phase.md` | How learning works, when it resets |
  75. | `ad_relevance_diagnostics.md` | Quality, Engagement, Conversion rankings |
  76. | `auction_overlap.md` | When your ads compete against each other |
  77. | `pacing.md` | Budget and bid pacing mechanics |
  78. | `bid_strategies.md` | Spend-based, goal-based, manual bidding |
  79. | `ad_auctions.md` | How auction winners are determined |
  80. | `performance_fluctuations.md` | Normal vs. concerning performance changes |
  81. ## License
  82. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.