Fb 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)

Group	Tools	What It Does
core	8	Account management, token tools, tool loading
crud	21	Create/read/update campaigns, ad sets, ads, creatives
insights	5	Performance data and breakdowns
analytics	7	Trends, fatigue detection, saturation analysis
targeting	3	Interest search, audience estimation, suggestions
pages	5	Facebook Page management and insights
instagram	4	Instagram account and media management
ad_library	2	Competitor ad research
creative_gen	7	AI image and video generation
image_editing	9	Upscale, remove BG, reimagine, recolor, inpaint
stock	3	Search Freepik image/icon/video libraries
audio	3	AI music, sound effects, vocal isolation

Full tool reference: docs/mcp-tools.md

Agents

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

Agent	What It Does
Report Agent	Generates KPMG-style PDF reports with charts and KPIs
Market Analyst	Audience research, demographic analysis, expansion planning
Creative Strategist	Ad copy, messaging angles, A/B test design
Creative Generator	AI image/video generation with brand-aware prompts
Performance Optimizer	Data-driven optimization recommendations
Competitive Intel	Ad Library research, competitor strategy analysis
Ads Optimizer	Campaign-level optimization (deprecated, kept for reference)

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

Slash Commands

Command	What It Does
/fb-ads:onboard-client	Set up a new client (interactive wizard)
/fb-ads:daily-check	Morning health check on your ad account
/fb-ads:weekly-report	Weekly performance summary
/fb-ads:optimize	Analyze and get optimization recommendations
/fb-ads:new-campaign	Interactive campaign creation wizard
/fb-ads:creative-refresh	Check for creative fatigue + guide refresh
/fb-ads:generate-creative	Generate AI images/videos for ads
/fb-ads:competitor-check	Research competitor ads via Ad Library

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:

Provider	Models	Key Required
Freepik	14 image + 24 video + editing	FREEPIK_API_KEY
Google Gemini	Imagen 3 + Veo	GEMINI_API_KEY
OpenAI	DALL-E 3 + Sora	OPENAI_API_KEY

See docs/freepik.md for model selection guides.

Documentation

Doc	Contents
Setup Guide	Step-by-step installation and credential setup
MCP Tools Reference	All 77 tools by group with descriptions
Agents & Clients	Agent system, onboarding, code structure
Freepik Guide	AI models, editing operations, parameters
Dashboard	Client dashboard architecture and deployment

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.