Meta MCP Connector

MCP-Server in einfacher Sprache für Meta / Facebook Ads über die Graph API.

Fragen Sie in natürlicher Sprache nach Werbekonten, Kampagnen, Anzeigengruppen, Ausgaben und Leistung – keine Tabellennamen oder rohen API-Pfade erforderlich.

Funktionen

• Live-Daten von der Facebook Marketing API (Graph API)

• Werbekonten mit übergeordnetem Business Manager auflisten

• Kampagnen-/Anzeigengruppen-/Anzeigenleistung (Ausgaben, Impressionen, Klicks, Käufe)

• Dashboard für Ausgaben auf Kontenebene (account-spend.html)

• Claude.ai OAuth bei Bereitstellung auf Cloud Run (MCP_PUBLIC_URL)

Related MCP server: Instagram Ads MCP Server

Projektstruktur

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)

Einrichtung (lokal)

1. Klonen und installieren

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. .env konfigurieren

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-Anforderungen

• Muss ein Benutzer-Token (EAA…) sein, kein App-Token (app_id|secret)

• Generiert im Graph API Explorer für Ihre FACEBOOK_APP_ID

• Berechtigungen: ads_read, ads_management, business_management

Verwenden Sie get-token.html oder starten Sie den Server und öffnen Sie http://127.0.0.1:8001/get-token.

3. Server starten

python meta_mcp_server.py --http

4. Cursor-MCP-Konfiguration

.cursor/mcp.json:

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

Laden Sie MCP in den Cursor-Einstellungen neu, nachdem Sie den Server gestartet haben.

MCP-Tools

Beispiel-Prompts

• "Liste meine Meta-Werbekonten auf"

• "Meta-Anzeigenzusammenfassung von 2026-08-01 bis 2026-08-15"

• "Tägliche Ausgaben der letzten 7 Tage für WOW Ad Account"

• "Top-Anzeigen nach Ausgaben von gestern"

• "Ausgaben nach Kampagne letzte Woche aufschlüsseln"

Google Cloud Run

Hosten Sie denselben HTTP-MCP-Endpunkt auf Cloud Run (gleiches Muster wie vdp-connector). Das Docker-Image enthält keine .env- oder Geheimniswerte.

Voraussetzungen

• Google Cloud SDK (gcloud) installiert und angemeldet (gcloud auth login)

• Ein GCP-Projekt mit aktivierter Abrechnung

• Ihre GCP-Projekt-ID

• Facebook-Anmeldedaten bereit in lokaler .env (siehe .env.example)

Bereitstellen

Aus diesem Repository-Ordner:

# 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"

Was das Skript tut:

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

2. Lädt FACEBOOK_APP_SECRET in den Secret Manager hoch (meta-facebook-app-secret)

3. Lädt FACEBOOK_ACCESS_TOKEN in den Secret Manager hoch (meta-facebook-access-token), falls in .env gesetzt

4. Stellt mit --source . (Dockerfile), Umgebungsvariablen und Secret-Injektion bereit

5. Setzt MCP_PUBLIC_URL auf die Service-URL (erforderlich für Claude OAuth)

6. Gibt die Connector-URL aus: https://SERVICE-URL/mcp

Bereitstellungs-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 (erforderlich für eine funktionierende MCP-URL beim ersten Bereitstellen)

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

Cursor (Cloud Run)

Nach der Bereitstellung fügen Sie die gedruckte URL in .cursor/mcp.json ein:

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

Sie benötigen keinen lokalen python meta_mcp_server.py-Prozess, wenn Sie Cloud Run verwenden.

Claude-Custom-Connector

Claude.ai erfordert OAuth für entfernte Custom-Connectors. Dieser Server enthält einen Claude-kompatiblen OAuth-Anbieter (Dynamic Client Registration), wenn MCP_PUBLIC_URL gesetzt ist (das Bereitstellungsskript setzt es automatisch).

1. Bereitstellen mit .\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID"

2. Entfernen Sie einen alten defekten Connector

3. Einstellungen → Connectors → Custom-Connector hinzufügen

4. Fügen Sie genau ein: https://YOUR-CLOUD-RUN-URL/mcp (muss /mcp enthalten)

5. Lassen Sie OAuth-Client-ID in den erweiterten Einstellungen leer (DCR ist aktiviert)

6. Klicken Sie auf Verbinden – Claude registriert sich selbst und autorisiert kurz

Wenn Sie "Couldn't register with … sign-in service" (ofid_…) sehen:

• Bestätigen Sie, dass die URL mit /mcp endet (nicht der bloße Cloud-Run-Host)

• Bestätigen Sie, dass der Dienst läuft: Öffnen Sie https://YOUR-CLOUD-RUN-URL/.well-known/oauth-authorization-server – Sie sollten JSON mit registration_endpoint sehen

• Bestätigen Sie, dass MCP_PUBLIC_URL mit dem Dienst-Ursprung übereinstimmt (erneut bereitstellen, wenn Sie die URL geändert haben)

• Fügen Sie keine zufällige OAuth-Client-ID ein, es sei denn, Sie haben einen externen IdP eingerichtet

Bereitstellung überprüfen

Lokal vs. Cloud

Sicherheitshinweis

--allow-unauthenticated macht die Cloud-Run-URL öffentlich erreichbar. OAuth bedeutet, dass Claude die Registrierung/Autorisierung abschließen muss, bevor Tools funktionieren; zufällige Aufrufer ohne Token erhalten 401. Behandeln Sie die URL dennoch als sensibel und fügen Sie eine stärkere Authentifizierung hinzu, bevor Sie sie weit verbreiten.

Häufige Fallstricke

1. Claude-URL ohne /mcp → „Couldn't connect to the server"

2. MCP_PUBLIC_URL nicht gesetzt → OAuth 404 → „Couldn't register with sign-in service"

3. Einchecken von .env- oder Geheimnisdateien

4. Vergessen, nach OAuth-Codeänderungen erneut bereitzustellen

5. Bereitstellen ohne FACEBOOK_ACCESS_TOKEN → Graph API gibt Berechtigungsfehler zurück

Auf GitHub pushen

# 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

Sicherheit

• Committen Sie niemals .env – es ist gitignored

• FACEBOOK_ACCESS_TOKEN ist ein Geheimnis; rotieren Sie es, falls es offengelegt wurde

• Die Cloud-Run-Bereitstellung verwendet --allow-unauthenticated für die Erreichbarkeit der MCP-URL; OAuth schützt den Tool-Zugriff, wenn MCP_PUBLIC_URL gesetzt ist