Meta MCP Connector

Plain-language MCP server for Meta / Facebook Ads via the Graph API.

Ask about ad accounts, campaigns, ad sets, spend, and performance in natural language — no table names or raw API paths required.

Features

• Live data from the Facebook Marketing API (Graph API)

• List ad accounts with parent Business Manager

• Campaign / ad set / ad performance (spend, impressions, clicks, purchases)

• Account-level spend dashboard (account-spend.html)

• Claude.ai OAuth when deployed to Cloud Run (MCP_PUBLIC_URL)

Related MCP server: Instagram Ads MCP Server

Project structure

meta-mcp-connector/
├── meta_mcp_server.py    # MCP server + HTTP routes + tools
├── meta_graph.py         # Facebook Graph API client
├── meta_oauth.py         # Claude-compatible OAuth provider
├── account-spend.html    # Spend-by-account dashboard
├── test-accounts.html    # Ad account list test page
├── get-token.html        # Helper to obtain FACEBOOK_ACCESS_TOKEN
├── requirements.txt
├── Dockerfile
├── deploy-cloudrun.ps1   # Deploy to Google Cloud Run
├── .env.example
└── .cursor/mcp.json      # Local Cursor MCP config (example)

Setup (local)

1. Clone and install

git clone https://github.com/YOUR_USERNAME/meta-mcp-connector.git
cd meta-mcp-connector
python -m venv .venv

# Windows
.venv\Scripts\activate

pip install -r requirements.txt
copy .env.example .env

2. Configure .env

FACEBOOK_APP_ID=your_app_id
FACEBOOK_APP_SECRET=your_app_secret
FACEBOOK_ACCESS_TOKEN=your_user_token_with_ads_read
FACEBOOK_AD_ACCOUNT_ID=114810198697538

Token requirements

• Must be a User Token (EAA…), not an App Token (app_id|secret)

• Generated in Graph API Explorer for your FACEBOOK_APP_ID

• Permissions: ads_read, ads_management, business_management

Use get-token.html or run the server and open http://127.0.0.1:8001/get-token.

3. Start the server

python meta_mcp_server.py --http

4. Cursor MCP config

.cursor/mcp.json:

{
  "mcpServers": {
    "meta": {
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}

Reload MCP in Cursor settings after starting the server.

MCP tools

Example prompts

• "List my Meta ad accounts"

• "Meta ads summary from 2026-08-01 to 2026-08-15"

• "Daily spend last 7 days for WOW Ad Account"

• "Top ads by spend yesterday"

• "Break down spend by campaign last week"

Google Cloud Run

Host the same HTTP MCP endpoint on Cloud Run (same pattern as vdp-connector). The Docker image does not bake in .env or secrets.

Prerequisites

• Google Cloud SDK (gcloud) installed and logged in (gcloud auth login)

• A GCP project with billing enabled

• Your GCP Project ID

• Facebook credentials ready in local .env (see .env.example)

Deploy

From this repo folder:

# App secret read from .env
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID"

# Optional overrides
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -Region "us-central1" -Service "meta-mcp"

# App secret from a one-line file (gitignored)
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -SecretFile ".\facebook-app-secret.key"

What the script does:

1. Enables Cloud Run, Cloud Build, Secret Manager, Artifact Registry

2. Uploads FACEBOOK_APP_SECRET → Secret Manager (meta-facebook-app-secret)

3. Uploads FACEBOOK_ACCESS_TOKEN → Secret Manager (meta-facebook-access-token) if set in .env

4. Deploys with --source . (Dockerfile), env vars, and secret injection

5. Sets MCP_PUBLIC_URL to the service URL (required for Claude OAuth)

6. Prints the connector URL: https://SERVICE-URL/mcp

Deploy flags:

• --set-env-vars MCP_TRANSPORT=http,HOST=0.0.0.0,FACEBOOK_APP_ID=…,FACEBOOK_AD_ACCOUNT_ID=…

• --set-secrets FACEBOOK_APP_SECRET=meta-facebook-app-secret:latest,FACEBOOK_ACCESS_TOKEN=meta-facebook-access-token:latest

• --allow-unauthenticated (needed for a working MCP URL on first deploy)

• --session-affinity, --max-instances 1, --timeout 300, --port 8080

Cursor (Cloud Run)

After deploy, put the printed URL in .cursor/mcp.json:

"meta": {
  "url": "https://YOUR-CLOUD-RUN-URL/mcp"
}

You do not need a local python meta_mcp_server.py process when using Cloud Run.

Claude custom connector

Claude.ai requires OAuth for remote custom connectors. This server embeds a Claude-compatible OAuth provider (Dynamic Client Registration) when MCP_PUBLIC_URL is set (the deploy script sets it automatically).

1. Deploy with .\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID"

2. Remove any old broken connector

3. Settings → Connectors → Add custom connector

4. Paste exactly: https://YOUR-CLOUD-RUN-URL/mcp (must include /mcp)

5. Leave OAuth Client ID empty in Advanced settings (DCR is enabled)

6. Click Connect — Claude registers itself and authorizes briefly

If you see "Couldn't register with … sign-in service" (ofid_…):

• Confirm the URL ends with /mcp (not the bare Cloud Run host)

• Confirm the service is up: open https://YOUR-CLOUD-RUN-URL/.well-known/oauth-authorization-server — you should see JSON with registration_endpoint

• Confirm MCP_PUBLIC_URL matches the service origin (redeploy if you changed the URL)

• Do not paste a random OAuth Client ID unless you set up an external IdP

Verify deployment

Local vs Cloud

Security note

--allow-unauthenticated makes the Cloud Run URL publicly reachable. OAuth means Claude must complete registration/authorize before tools work; random callers without a token get 401. Still treat the URL as sensitive and add stronger auth before sharing widely.

Common pitfalls

1. Claude URL missing /mcp → "Couldn't connect to the server"

2. MCP_PUBLIC_URL not set → OAuth 404 → "Couldn't register with sign-in service"

3. Committing .env or secret files

4. Forgetting to redeploy after OAuth code changes

5. Deploying without FACEBOOK_ACCESS_TOKEN → Graph API returns permission errors

Push to GitHub

# Sign in to your new GitHub account first
git credential-manager github login --force

# Create repo on GitHub (browser or gh), then:
git remote add origin https://github.com/YOUR_USERNAME/meta-mcp-connector.git
git add .
git commit -m "Initial commit: Meta MCP connector"
git push -u origin main

Security

• Never commit .env — it is gitignored

• FACEBOOK_ACCESS_TOKEN is a secret; rotate if exposed

• Cloud Run deploy uses --allow-unauthenticated for MCP URL reachability; OAuth protects tool access when MCP_PUBLIC_URL is set