# Clone the repository
git clone https://github.com/serkanhaslak/meta-mcp.git
cd meta-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your Meta credentials

# Run in development mode (with hot reload)
npm run dev

# Or build and run production
npm run build
npm start

# Build the image
docker build -t meta-mcp .

# Run the container
docker run -p 3000:3000 \
  -e MCP_API_KEY=your_api_key \
  -e META_ACCESS_TOKEN=your_token \
  -e META_AD_ACCOUNT_ID=act_123456789 \
  meta-mcp

META_MCP_URL=https://your-deployment-url.up.railway.app/mcp
MCP_API_KEY=your_api_key_here
META_ACCESS_TOKEN=your_meta_access_token_here

{
  "mcpServers": {
    "meta-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "${META_MCP_URL}",
        "--header",
        "Authorization: Bearer ${MCP_API_KEY}",
        "--header",
        "X-Meta-Token: ${META_ACCESS_TOKEN}"
      ]
    }
  }
}

{
  "mcpServers": {
    "meta-mcp": {
      "command": "node",
      "args": ["/path/to/meta-mcp/dist/index.js"],
      "env": {
        "META_ACCESS_TOKEN": "your_meta_access_token",
        "META_AD_ACCOUNT_ID": "act_123456789"
      }
    }
  }
}

{
  "mcpServers": {
    "meta-mcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/meta-mcp/src/index.ts"],
      "env": {
        "META_ACCESS_TOKEN": "your_meta_access_token",
        "META_AD_ACCOUNT_ID": "act_123456789"
      }
    }
  }
}

{
  "permissions": {
    "allow": [
      "mcp__meta-mcp__*"
    ]
  }
}

{
  "permissions": {
    "allow": [
      "mcp__meta-mcp__list_*",
      "mcp__meta-mcp__get_*",
      "mcp__meta-mcp__search_*"
    ],
    "deny": [
      "mcp__meta-mcp__delete_*"
    ]
  }
}

{
  "mcpServers": {
    "meta-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-deployment-url.up.railway.app/mcp",
        "--header",
        "Authorization: Bearer YOUR_MCP_API_KEY",
        "--header",
        "X-Meta-Token: YOUR_META_ACCESS_TOKEN"
      ]
    }
  }
}

What Meta Ads tools do you have access to?

Create a new Meta Ads campaign:
- Objective: OUTCOME_LEADS
- Name: "Spring Sale 2025"
- Daily budget: $50
- Target: US, ages 25-45, interested in "Online Shopping"
- Use my Page for the creative with headline "50% Off Everything"
- Start running immediately

Show me the performance of all active campaigns for the last 7 days.
Break down by age and gender. Include spend, impressions, clicks, CPC, and ROAS.

Create a lookalike audience based on my "High Value Customers" custom audience.
Target the US with 1% similarity. Then create an ad set using this audience.

Create a rule that pauses any ad with CPC above $5 and more than 1000 impressions.
Check every 30 minutes. Send me a notification when it triggers.

Get the status and spend of all 25 campaigns in my account using a single batch request.

Copy my best performing campaign "Summer Promo" and create a variant
with a different headline for A/B testing.

curl -H "Authorization: Bearer YOUR_MCP_API_KEY" \
     -H "X-Meta-Token: YOUR_META_TOKEN" \
     -H "X-Meta-Account-Id: act_123456789" \
     https://meta-mcp.pragmaticgrowth.com/api/v1/campaigns

# Get user's ad accounts
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "X-Meta-Token: YOUR_META_TOKEN" \
     "https://meta-mcp.pragmaticgrowth.com/api/v1/meta/me/adaccounts?fields=id,name&limit=5"

# Get campaign insights
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "X-Meta-Token: YOUR_META_TOKEN" \
     "https://meta-mcp.pragmaticgrowth.com/api/v1/meta/act_123/insights?fields=spend,impressions&date_preset=last_7d"

curl https://meta-mcp.pragmaticgrowth.com/health

{
  "status": "ok",
  "name": "meta-mcp",
  "version": "1.0.0",
  "tools": 77,
  "modes": ["mcp", "rest"],
  "uptime": 3600.5
}

meta-mcp/
├── src/
│   ├── index.ts              # Server entry — Fastify setup, MCP endpoint, session management
│   ├── client.ts             # MetaApiClient — Graph API wrapper with retries and rate limiting
│   ├── types.ts              # TypeScript interfaces for API responses
│   ├── tools/                # 24 tool modules (77 total tools)
│   │   ├── index.ts          # Tool registration hub
│   │   ├── account.ts        # Account management tools
│   │   ├── campaigns.ts      # Campaign CRUD
│   │   ├── adsets.ts         # Ad set management
│   │   ├── ads.ts            # Ad management
│   │   ├── creatives.ts      # Creative assets
│   │   ├── images.ts         # Image upload/management
│   │   ├── videos.ts         # Video upload/management
│   │   ├── audiences.ts      # Custom & lookalike audiences
│   │   ├── saved-audiences.ts# Saved audience segments
│   │   ├── insights.ts       # Performance analytics
│   │   ├── targeting.ts      # Interest/behavior/geo/demo search
│   │   ├── targeting-utils.ts# Targeting validation & suggestions
│   │   ├── conversions.ts    # Conversions API (server-side tracking)
│   │   ├── custom-conversions.ts # URL-based conversion rules
│   │   ├── pixel.ts          # Meta Pixel management
│   │   ├── leadgen.ts        # Lead generation forms
│   │   ├── rules.ts          # Automated rules
│   │   ├── previews.ts       # Ad preview rendering
│   │   ├── copies.ts         # Campaign/adset/ad duplication
│   │   ├── batch.ts          # Batch API operations
│   │   ├── labels.ts         # Label management
│   │   ├── budget-schedules.ts # Budget scheduling
│   │   ├── activities.ts     # Audit activity logs
│   │   └── reach-estimate.ts # Reach/frequency estimation
│   ├── landing.ts            # Landing page HTML (served at /)
│   ├── swagger-theme.ts      # Dark theme CSS for Swagger UI
│   ├── rest/
│   │   ├── proxy.ts          # REST API routes and Graph API proxy
│   │   └── schemas.ts        # Zod schemas for OpenAPI documentation
│   └── utils/
│       ├── default-fields.ts # Pre-configured API field selections
│       ├── rate-limiter.ts   # BUC-based adaptive rate limiting
│       ├── pagination.ts     # Cursor-based pagination helper
│       ├── sleep.ts          # Async delay utility
│       └── tool-response.ts  # Response formatting helpers
├── .env.example              # Environment variable template
├── .mcp.json.example         # MCP client configuration template
├── Dockerfile                # Docker containerization
├── package.json              # Dependencies and scripts
└── tsconfig.json             # TypeScript configuration

┌─────────────┐     MCP Protocol      ┌──────────────┐     Graph API     ┌──────────────┐
│ Claude Code  │◄────── /mcp ────────►│   meta-mcp   │◄───────────────►│  Meta API    │
│ Claude Desktop│   (Streamable HTTP)  │   (Fastify)  │   (Rate-limited) │ graph.fb.com │
└─────────────┘                        └──────────────┘                  └──────────────┘
                                             ▲
┌─────────────┐     REST API           │
│ n8n / curl  │◄── /api/v1/* ─────────┘
│ Postman     │   (JSON over HTTP)
└─────────────┘

version: "3.8"
services:
  meta-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - MCP_API_KEY=${MCP_API_KEY}
      - META_ACCESS_TOKEN=${META_ACCESS_TOKEN}  # optional fallback
      - META_AD_ACCOUNT_ID=${META_AD_ACCOUNT_ID}  # optional fallback
      - PORT=3000
    restart: unless-stopped

# Start with env vars directly
MCP_API_KEY=your_secret_key \
META_ACCESS_TOKEN=your_token \
META_AD_ACCOUNT_ID=act_123456789 \
PORT=3000 \
node dist/index.js