Overview

This repository provides a remote MCP (Model Context Protocol) server that exposes Meta Ads (Facebook/Instagram) campaign management and reporting capabilities as HTTP tools. The server acts as a bridge between LLM-based agents or other automation systems and the Meta Ads API, packaging common operations — fetching campaigns, pulling insights, creating/updating campaign objects, and estimating reach — behind a small, consistent JSON API.

Using a dedicated MCP server is useful when you want to centralize access control, caching, and business logic for ad operations, or when you need to let AI agents operate on ad accounts without embedding long-lived access tokens in multiple places. It simplifies rate-limit handling, logging, and batching, and can be run as a reusable service in staging/production environments.

Features

Tool-style HTTP endpoints for common Meta Ads operations (read/write)
Insights / metrics retrieval with time range and breakdowns
Campaign, ad set, and ad object creation and updates
Batch operations (bulk budget updates, status changes)
Caching and simple rate-limit safeguards
Token-based authorization for tool calls
Health and metadata endpoints (OpenAPI or tool manifest)
Optional support for multi-account and staging workflows
JSON output optimized for programmatic consumption

Installation / Configuration

Prerequisites:

Docker & Docker Compose (recommended) or Node.js (if running locally)
A Meta (Facebook) API access token with the appropriate permissions
A secret token to protect the MCP server endpoints

Clone and run with Docker Compose:

git clone https://github.com/pipeboard-co/meta-ads-mcp.git
cd meta-ads-mcp
cp .env.example .env
# edit .env to add credentials
docker compose up -d

Example docker-compose.yml (trimmed):

version: "3.8"
services:
  mcp:
    image: pipeboard/meta-ads-mcp:latest
    ports:
      - "8080:8080"
    env_file:
      - .env
  redis:
    image: redis:6
    restart: always

Example .env (required keys):

PORT=8080
MCP_SECRET=replace_with_secure_token
META_ACCESS_TOKEN=EAAB...your_token_here
CACHE_TTL=300
LOG_LEVEL=info

Run locally (Node.js approach, if provided by repo):

npm install
npm run start

The server will listen on the configured PORT (default 8080) and expose endpoints described below. Protect MCP_SECRET and META_ACCESS_TOKEN; run behind a private network or an authenticated gateway in production.

Environment variables reference:

Name	Purpose	Default
PORT	Server port	8080
MCP_SECRET	Bearer token to authorize calls	(none)
META_ACCESS_TOKEN	Meta Graph API token	(none)
CACHE_TTL	Caching TTL (seconds)	300
LOG_LEVEL	Logging verbosity (info/debug)	info

Available Tools / Resources

Common tools the server typically exposes (HTTP JSON endpoints):

GET /health
GET /tools (list available tools and metadata)
POST /tool/fetch_campaigns
- params: account_id, fields, limit
POST /tool/fetch_insights
- params: account_id, since, until, level, breakdowns
POST /tool/create_campaign
- params: account_id, name, objective, status, budget
POST /tool/update_campaign
- params: campaign_id, updates (budget, status, bid)
POST /tool/batch_update_budgets
- params: updates: [{campaign_id, daily_budget}, …]
POST /tool/estimate_reach
- params: account_id, targeting_spec, daily_budget
POST /tool/preview_ad
- params: ad_id

Tool calls generally expect a JSON body and an Authorization header:

curl -X POST http://localhost:8080/tool/fetch_insights \
  -H "Authorization: Bearer $MCP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"act_12345","since":"2024-03-01","until":"2024-03-07","level":"ad"}'

Additional resources often provided by the server:

OpenAPI / Swagger UI (e.g., /openapi.json or /docs)
Postman collection or example workspace
Example agent integrations for common LLM toolkits

Use Cases

Automated daily pacing: run a scheduled job that calls fetch_insights, compares spend vs target, and uses batch_update_budgets to raise or lower daily budgets to meet pacing goals.
Creative performance analysis: fetch ad-level metrics (CTR, CPC, conversions) across campaigns, compute statistical significance between creatives, and flag low-performing variants for replacement.
Client reporting and exports: programmatically pull account-level insights on a monthly cadence and serialize to CSV/JSON for dashboarding or client delivery.
A/B testing orchestration: create campaigns/ad sets programmatically via create_campaign, monitor results with fetch_insights, and automatically promote the winner by reallocating budget.
Safe LLM integration: expose a curated set of ad management operations to an LLM agent while keeping Meta API tokens centralized and auditable; apply rate limits and logging for compliance.

Security & Operational Notes

Always run the server behind a secure network boundary and rotate MCP_SECRET and META_ACCESS_TOKEN routinely.
Use scopes and short-lived tokens when possible for Meta API access.
Be mindful of Meta rate limits; use caching and batching endpoints to reduce calls.
Add monitoring for errors and failed writes to avoid accidental ad spend changes.

This MCP server is intended to be an integration layer

Remote MCP Server for Meta Ads API