Facebook Ads Automation

An MCP server for Claude Code that gives you full read/write access to the Meta Marketing API. Manage campaigns, analyze performance, generate AI creatives, and get optimization recommendations — all through natural language.

77 MCP tools | 7 AI agents | PDF reports | AI creative generation | Multi-account support

Built on FastMCP + Facebook Marketing API v24.0.

How It Works

YOU (natural language in Claude Code)
  |
  v
SLASH COMMANDS      /fb-ads:daily-check, /fb-ads:weekly-report, /fb-ads:optimize, ...
  |
  v
AGENTS (7)          Report, Market Analyst, Creative Strategist, Creative Generator,
                    Performance Optimizer, Competitive Intel, Ads Optimizer
  |
  v
KNOWLEDGE           Per-client context: business goals, brand voice, audience, competitors
  |
  v
MCP SERVER (77)     Facebook API tools + Analytics engine + AI creative generation

What You Can Do

• Manage campaigns — Create, read, update, pause/activate campaigns, ad sets, ads, and creatives

• Analyze performance — Get insights, run analytics, detect creative fatigue, check audience saturation

• Generate creatives — AI image/video generation via Freepik (14 image + 24 video models), Gemini (Imagen 3 + Veo), and OpenAI (DALL-E 3 + Sora)

• Edit images — Upscale, remove backgrounds, reimagine, recolor, inpaint, and more (9 editing operations)

• Optimize — Get data-driven recommendations based on your KPIs, thresholds, and business rules

• Generate reports — KPMG-style PDF reports with charts, KPIs, and recommendations

• Research competitors — Search the Facebook Ad Library and analyze competitor strategies

• Manage multiple accounts — Switch between ad accounts with labeled aliases

Quick Start

1. Install

git clone https://github.com/your-username/fb-ads-automation.git
cd fb-ads-automation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configure

cp .env.example .env
cp .mcp.json.example .mcp.json

Edit .env with your Facebook credentials (see Setup Guide for step-by-step instructions on getting each credential):

FB_APP_ID=your_app_id
FB_APP_SECRET=your_app_secret
FB_ACCESS_TOKEN=your_access_token
FB_AD_ACCOUNT_ID=act_your_account_id

Edit .mcp.json with absolute paths to your Python and server:

{
  "mcpServers": {
    "fb-ads": {
      "command": "/absolute/path/to/.venv/bin/python3",
      "args": ["/absolute/path/to/fb_ads_mcp_server/server.py"]
    }
  }
}

3. Verify

Open Claude Code in the project directory:

check_token_status

If you see your token info, you're ready.

4. Onboard Your First Client

/fb-ads:onboard-client

This interactive wizard validates your account, interviews you about your business, and creates the knowledge files that agents use.

Tool Groups

Only 8 core tools load at startup. Load more on demand:

enable_tools(groups="crud,insights")   # Campaign management + reporting
enable_tools(groups="creative_gen")    # AI image/video generation
enable_tools(groups="all")             # Everything (77 tools)

Full tool reference: docs/mcp-tools.md

Agents

Seven specialized agents live in agents/. Activate by saying "Load [agent name]":

Agents auto-read your knowledge files for business context, brand voice, audience data, and competitive landscape.

Slash Commands

Knowledge System

Agents use per-client knowledge files to understand your business:

knowledge/
  playbook.md              # Global optimization thresholds
  accounts.md              # Account registry
  report-specs.md          # PDF report configuration
  clients/
    _templates/            # Blank templates to copy
    _example/              # Filled example (fictional cafe)
    your-client/           # Your client's knowledge files
      business-context.md  # Company, product, KPIs, strategy
      brand-voice.md       # Tone, messaging, visual direction
      audience-research.md # Segments, demographics, saturation
      competitive-landscape.md  # Competitors, benchmarks, gaps

Important Notes

Budgets use the smallest currency unit. USD uses cents ($50/day = daily_budget: 5000). INR uses paisa (Rs 1,000/day = daily_budget: 100000).

Campaign objectives must be OUTCOME-based: OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_AWARENESS, OUTCOME_SALES, OUTCOME_APP_PROMOTION.

Rate limits are ~200 API calls/hour/user. Analytics tools make multiple calls per invocation.

Tokens expire after ~60 days. Use check_token_status and refresh_access_token to manage them.

Optional: AI Creative Generation

The core ads management works without these. Add API keys for creative generation:

See docs/freepik.md for model selection guides.

Documentation

Project Structure

fb_ads_mcp_server/         # MCP server
  server.py                # Entry point (FastMCP)
  api/                     # Pure Facebook SDK wrappers (no MCP coupling)
  tools/                   # MCP tool registration (thin orchestrators)
  analytics/               # Pure computation functions
  rules/                   # Business rule engine
  providers/               # AI provider abstraction (Gemini, OpenAI, Freepik)
agents/                    # 7 agent instruction files
knowledge/                 # Global + per-client knowledge files
reports/                   # PDF report generator + charts
dashboard/                 # Static client dashboard (Netlify-ready)
docs/                      # Documentation
tests/                     # Test suite

Contributing

See CONTRIBUTING.md for development setup, testing, and PR guidelines.

License

MIT - see LICENSE.