FA
Developer Tools

Facebook Ads MCP Server for Programmatic API Access

Access Facebook Ads programmatically with an MCP server to manage campaigns, retrieve analytics, and automate ad operations via the API.

View on GitHub
Quick Install
npx -y @gomarble-ai/facebook-ads-mcp-server

Overview

This MCP (Model Context Protocol) server exposes Facebook Ads functionality as callable tools so applications and LLM-based agents can manage campaigns, retrieve analytics, and automate ad operations programmatically. The server wraps the Facebook Marketing API behind a small HTTP service that implements the MCP tools interface, enabling safe, auditable calls from models or developer scripts without embedding long-lived API keys directly in prompts.

By centralizing Facebook Ads operations into discrete tools — create campaign, adjust budgets, fetch insights, pause ads, etc. — teams can build automation, reporting pipelines, and AI-driven optimizers that operate at scale. The server provides authentication, request validation, and a stable tool catalog so developers and agents can interact with ad accounts in a predictable way.

Features

  • Exposes Facebook Marketing API actions as MCP-style tools
  • Tool definitions for campaign, adset, ad, creative, and insights operations
  • Environment-based configuration for Facebook credentials and account IDs
  • Example endpoints and JSON schemas for use by LLM agents or automation scripts
  • Lightweight HTTP server suitable for local development or container deployment
  • Logging and basic error handling for operational visibility

Installation / Configuration

Prerequisites:

  • Node.js 16+ (or the runtime indicated in the repository)
  • A Facebook App and a valid Marketing API access token with permissions for the ad account

Quick start (Node/npm):

git clone https://github.com/gomarble-ai/facebook-ads-mcp-server.git
cd facebook-ads-mcp-server
npm install
cp .env.example .env
# Edit .env to add your Facebook credentials and ad account ID
npm run start

Example .env (replace placeholders):

FACEBOOK_APP_ID=your-app-id
FACEBOOK_APP_SECRET=your-app-secret
FACEBOOK_ACCESS_TOKEN=your-access-token
FACEBOOK_API_VERSION=v17.0
AD_ACCOUNT_ID=act_1234567890
MCP_SERVER_PORT=8080
LOG_LEVEL=info

Run with Docker:

# Build
docker build -t facebook-ads-mcp-server .

# Run (pass env vars or mount a .env file)
docker run -p 8080:8080 \
  -e FACEBOOK_ACCESS_TOKEN=your-access-token \
  -e AD_ACCOUNT_ID=act_1234567890 \
  facebook-ads-mcp-server

Configuration notes:

  • Store access tokens securely (secrets manager, not plain text) in production.
  • The server supports a single ad account per instance by default; running multiple instances or adding account-selection logic is possible.

Available Tools

The server exposes a set of tools that map to common Facebook Ads workflows. Each tool accepts a JSON payload and returns structured JSON results.

  • create_campaign
    • Create a new campaign with objective, name, and status.
    • Params: name, objective, status, special_ad_categories (optional)
  • update_campaign
    • Update campaign fields like name or status.
    • Params: campaign_id, fields
  • create_adset
    • Create an ad set under a campaign with budget, schedule, targeting.
    • Params: campaign_id, name, daily_budget, start_time, end_time, targeting
  • create_ad
    • Create an ad and link creative and adset.
    • Params: adset_id, creative_id, name, status
  • update_ad
    • Update ad status or creative.
    • Params: ad_id, fields
  • get_insights
    • Retrieve performance metrics for campaigns/adsets/ads over a date range.
    • Params: level (campaign|adset|ad), ids[], since, until, fields[]
  • list_campaigns / list_adsets / list_ads
    • List entities for the configured ad account.
    • Params: optional filters and paging
  • pause_campaign / resume_campaign
    • Change campaign status to PAUSED or ACTIVE.
    • Params: campaign_id

Example tool request shape (POST /tools/get_insights):

POST /tools/get_insights
Content-Type: application/json

{
  "level": "campaign",
  "ids": ["1234567890"],
  "since": "2026-03-01",
  "until": "2026-03-31",
  "fields": ["impressions","clicks","spend","actions"]
}

Response will include aggregated metrics and any paging cursors returned by the Facebook API.

Use Cases

  • Daily automated budget tuning: run a scheduled job that calls get_insights for the last 24 hours, compute ROAS, and call update_adset or update_campaign to increase budgets on high-performing groups and reduce budgets on low performers.
  • Automated reporting: a reporting service aggregates get_insights across campaigns and formats CSV or dashboards for stakeholders.
  • On-demand campaign creation: a frontend or LLM agent can call create_campaign -> create_adset -> create_ad in sequence to spin up test campaigns for experiments without manual dashboard work.
  • Emergency shutdown: in case of anomaly, an operator or agent can call pause_campaign or update_ad to immediately stop spend on specific campaigns or ad sets.
  • A/B testing orchestration: programmatically create multiple creatives and ad variations, then use insights to determine winners and automatically scale them.

Troubleshooting & Resources

  • Common issues:
    • 400/403 from Facebook: verify access token permissions and that the token is not expired.
    • Rate limiting: implement retries with exponential backoff; monitor headers for X-Ads-Rate-Limit info.
  • Logs: check server logs to see API requests, responses, and errors. Increase LOG_LEVEL for debugging.
  • Resources:
    • Facebook Marketing API docs: https://developers.facebook.com/docs/marketing-apis/
    • Repository: https://github.com/gomarble-ai/facebook-ads-mcp-server

If you plan to integrate this server into production workflows, review Facebook’s rate limits and data handling policies, secure your credentials, and add additional validation and monitoring around ad operations.

Tags:developer-tools