Microsoft Advertising MCP Connector

Eigenständiger True Model B MCP-Server für Claude.ai Custom Connectors. Ein Betreiber kann mehrere Microsoft-Konten verbinden. Jede Verbindung kann mehrere Microsoft Advertising-Kunden und Werbekonten sehen.

Dies ist nicht Teil von Google All-in-One connector. Es hat keine Laufzeitabhängigkeit von diesem Projekt, keine gemeinsamen Firestore-Sammlungen und keine gemeinsamen OAuth-Tokens.

Claude.ai
   │  MCP OAuth 2.1
   ▼
operatorId
   ├── Microsoft Connection A → customers → advertising accounts → campaigns / reports
   ├── Microsoft Connection B
   └── Microsoft Connection C

Der sub des MCP-JWT ist immer die interne operatorId. Der sub von Microsoft OpenID existiert nur auf bing_mcp_microsoft_connections.microsoftSubjectId. E-Mail ist Anzeigemetadaten, niemals ein Autorisierungsschlüssel.

Architektur

• Next.js 15 App Router + mcp-handler Streamable HTTP unter /mcp

• MCP OAuth 2.1 mit PKCE S256, DCR und Claude CIMD

• Microsoft Entra Autorisierungscode-Flow (common-Mandant)

• Microsoft Advertising REST v13 (nicht SOAP)

• Benannte Firestore-Datenbank bing-mcp-v1

• AES-256-GCM-Verschlüsselung von Refresh-Tokens im Ruhezustand

• Cloud Run (zustandslos; lauscht auf $PORT)

Related MCP server: Google Ads MCP Server

Anmeldedaten (das sind verschiedene Dinge)

Umgebung

Kopieren Sie .env.example in .env. Committen Sie .env niemals.

Erforderlich:

APP_BASE_URL
MICROSOFT_CLIENT_ID
MICROSOFT_CLIENT_SECRET
MICROSOFT_REDIRECT_URI
MICROSOFT_ADS_DEVELOPER_TOKEN
MCP_TOKEN_SECRET
OAUTH_STATE_SECRET
TOKEN_ENCRYPTION_KEY
FIRESTORE_PROJECT_ID
FIRESTORE_DATABASE_ID=bing-mcp-v1

FIRESTORE_DATABASE_ID muss bing-mcp-v1 sein. Der Start lehnt (default) und gconnect-mcp-all-v1 ab.

Microsoft Entra-App-Registrierung

1. Öffnen Sie Microsoft Entra-App-Registrierungen.

2. Erstellen Sie eine Registrierung.

3. Unterstützte Kontotypen: Konten in einem beliebigen Organisationsverzeichnis und persönliche Microsoft-Konten (damit common funktioniert).

4. Fügen Sie eine Web-Umleitungs-URI hinzu: {APP_BASE_URL}/oauth/microsoft/callback (lokales Beispiel: http://localhost:3000/oauth/microsoft/callback).

5. Erstellen Sie ein Client-Secret. Speichern Sie es in MICROSOFT_CLIENT_SECRET.

6. API-Berechtigungen: Delegierter Bereich von Microsoft Advertising https://ads.microsoft.com/msads.manage. Fordern Sie außerdem openid, profile, email und offline_access an.

7. Erteilen Sie die Administratorzustimmung, falls Ihr Mandant dies erfordert.

Offizielle Anleitungen:

• Authentifizierung mit OAuth

• Benutzerzustimmung anfordern

Entwicklertoken

Holen Sie sich ein Microsoft-Advertising-Entwicklertoken aus den Microsoft-Advertising-Entwicklereinstellungen. Sandbox-Token können selbst ausgestellt werden; Produktionstoken erfordern die Genehmigung von Microsoft.

Dieses Token ist eine Anmeldeinformation auf Anwendungsebene. Es wird als DeveloperToken-Header bei Advertising-REST-Aufrufen gesendet. Es wird niemals pro Betreiber gespeichert und darf niemals in MCP-Ausgaben oder Protokollen erscheinen.

Lokale Entwicklung

npm install
npm test
npm run typecheck
npm run dev

• Health: GET http://localhost:3000/health

• MCP: http://localhost:3000/mcp

• Microsoft-Callback: http://localhost:3000/oauth/microsoft/callback

Fügen Sie den Custom Connector in Claude.ai hinzu, der auf {APP_BASE_URL}/mcp zeigt. Claude führt den MCP-OAuth-Flow aus, dann leitet der Server den Browser zur Microsoft-Anmeldung weiter. Nach der Zustimmung kehren Sie zu Claude zurück.

Firestore lokal: entweder Application Default Credentials (gcloud auth application-default login) plus FIRESTORE_PROJECT_ID oder FIRESTORE_EMULATOR_HOST.

MCP-Tools (V1, schreibgeschützt)

Verbindungen: get_operator, list_microsoft_connections, get_microsoft_connection, start_microsoft_connection, disconnect_microsoft_connection

Kunden / Konten: list_microsoft_customers, get_microsoft_customer, list_microsoft_accounts, get_microsoft_account

Entitäten: list_campaigns, get_campaign, list_ad_groups, get_ad_group, list_ads, get_ad, list_keywords, get_keyword

Berichte (offizielle Reporting-API, asynchrones Senden/Abfragen/Herunterladen): get_account_performance, get_campaign_performance, get_ad_group_performance, get_keyword_performance

Wenn dasselbe Werbekonto über mehr als eine Microsoft-Verbindung sichtbar ist, gibt der Server einen Mehrdeutigkeitsfehler zurück und fragt nach connectionId. Er rät niemals.

Firestore-Sammlungen

Benannte Datenbank: bing-mcp-v1

• bing_mcp_operators

• bing_mcp_microsoft_connections

• bing_mcp_connection_uniques ({operatorId}_{microsoftSubjectId})

• bing_mcp_microsoft_customers

• bing_mcp_microsoft_accounts

• bing_mcp_oauth_transactions

• bing_mcp_sessions

Cloud Run

Der Cloud-Run-Ingress muss nicht authentifiziert sein. Die Authentifizierung erfolgt über MCP-JWT, nicht über Cloud IAM.

Das Cloud-Run-Dienstkonto benötigt Firestore-Zugriff auf die benannte Datenbank (roles/datastore.user ist üblich). Verwenden Sie Application Default Credentials. Committen Sie keine JSON-Datei des Dienstkontos.

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_PROJECT
.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_PROJECT
.\scripts\cloud-run-set-env.ps1 -ProjectId YOUR_PROJECT -AppBaseUrl https://... -MicrosoftClientId ... -MicrosoftClientSecret ... -McpTokenSecret ... -OauthStateSecret ... -TokenEncryptionKey ... -MicrosoftAdsDeveloperToken ...

Fügen Sie dann {APP_BASE_URL}/oauth/microsoft/callback zur Entra-App hinzu und fügen Sie den Claude Custom Connector unter {APP_BASE_URL}/mcp hinzu.

Das Service-Timeout beträgt 300 Sekunden, damit asynchrone Berichte abgeschlossen werden können.

Sicherheit

Niemals über MCP oder Protokolle offengelegt: Zugriffstoken, Refresh-Tokens, Client-Secrets, Entwicklertoken, Verschlüsselungsschlüssel, Autorisierungscodes.

Die Autorisierung verwendet operatorId + connectionId + Microsoft-IDs. Namen und E-Mails sind keine Autorisierungskennungen.

V2 (nicht implementiert)

Kampagnen erstellen/aktualisieren/pausieren, Schreibvorgänge für Anzeigengruppen und Anzeigen, Keyword-Schreibvorgänge, Budgetaktualisierungen.

Tests

npm test

Automatisierte Tests decken MCP-JWT-Identität, Microsoft-OAuth-State/Austausch/Refresh/invalid_grant, Betreiber-Isolation, Mehrfachverbindung, dieselbe Microsoft-Identität über Betreiber hinweg, Ablehnung mehrdeutiger Konten, CSV-Parsing von Berichten, Header-Regeln und Schwärzung von Geheimnissen ab.

Live-Pfade mit Claude, Microsoft-Anmeldung und Cloud Run erfordern Ihre Entra-App, Ihr Entwicklertoken und Ihr GCP-Projekt.