Google Analytics + AdSense Remote MCP

Ein schreibgeschützter Remote-MCP-Server für GA4 und die AdSense Management API v2, der auf Cloudflare Workers läuft. Für das HTTP-Routing wird Hono verwendet, für den MCP-Transport createMcpHandler(), und für die OAuth-Autorisierung des Clients wird Cloudflare Access Managed OAuth genutzt.

Ein einzelner Worker ist an ein Google-OAuth-Refresh-Token gebunden und behandelt alle GA4-Properties und AdSense-Konten, die dieses Google-Konto lesen kann. Es ist nicht möglich, OAuth-Anmeldedaten, Google-API-Hosts oder Schreiboperationen über Tool-Aufrufe auszutauschen.

Ein-Klick-Deployment auf Cloudflare

Der Button dupliziert dieses öffentliche GitHub-Repository in das eigene Konto und führt den Build und das Deployment mit dem Worker-Namen und den folgenden Einstellungen durch.

• Nicht-geheime Einstellungen: CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD

• Secrets: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN

GOOGLE_REFRESH_TOKEN muss vor dem Drücken des Buttons mit den weiter unten beschriebenen Schritten ausgestellt werden, wobei nur die Read-only-Scopes genehmigt werden. Die Cloudflare Access Application und die Aktivierung von Managed OAuth führt der Nutzer nach dem Deployment selbst durch.

Related MCP server: Google Analytics MCP server on Cloudflare Workers

Endpunkte

MCP-Tools

• ga4_run_report, ga4_run_realtime_report, ga4_run_pivot_report, ga4_run_funnel_report

• ga4_get_metadata, ga4_check_compatibility

• ga4_admin_read: GET/list-Operationen unter accountSummaries, accounts, properties der GA4 Admin API v1alpha.

• adsense_generate_report

• adsense_read: GET/list-Operationen unter accounts der AdSense Management API v2.

Alle Tools sind in MCP als schreibgeschützt annotiert, und die Eingaben werden mit Zod validiert. Externe URLs, beliebige HTTP-Header und die beliebige Ausführung von POST/PUT/PATCH/DELETE werden nicht akzeptiert. Rohe Google-Fehler werden nicht in die MCP-Antwort aufgenommen, aber für die Fehleranalyse werden die vollständigen Inhalte in den Worker Logs des Cloudflare-Zielkontos ausgegeben.

Vorbereitung von Google OAuth

1. Aktivieren Sie im Google Cloud Project die Google Analytics Data API, die Google Analytics Admin API und die AdSense Management API.

2. Richten Sie den OAuth-Zustimmungsbildschirm ein und fordern Sie nur https://www.googleapis.com/auth/analytics.readonly für GA4 und https://www.googleapis.com/auth/adsense.readonly für AdSense an.

3. Erstellen Sie unter Credentials eine OAuth-Client-ID und wählen Sie als Application type Desktop app. AdSense unterstützt keine Service Accounts; der Installed Application Flow ist erforderlich.

4. Da Refresh-Tokens unter Umständen nicht erneut angezeigt werden können, bewahren Sie sie bei der Ausstellung in einem sicheren Passwort-Manager auf. Sie dürfen nicht im Repository, in Issues, in CI-Logs oder in wrangler.jsonc abgelegt werden.

Google lässt Access-Tokens in kurzer Zeit ablaufen. Der Worker holt bei jeder Ausführung eines MCP-Tools ein neues Access-Token über den Refresh-Token-Grant, sodass der Worker keine Tokens dauerhaft speichern muss.

Ausstellen eines Refresh-Tokens mit Python

Es wird nur Python 3.10 oder höher benötigt, zusätzliche Pakete sind nicht erforderlich. scripts/get_google_refresh_token.py wartet mit PKCE auf einen lokalen Callback und speichert keine Anmeldedaten, Access-Tokens oder Refresh-Tokens in Dateien.

Redirect-URI-Einstellung in der Google Cloud Console

Dieser Worker empfängt keine Callbacks direkt von Google. Der unter Credentials erstellte OAuth-Client muss unbedingt eine Desktop app sein. Bei Desktop-Apps müssen Authorized redirect URIs und Authorized JavaScript origins in der Cloud Console nicht konfiguriert werden.

Das Python-Skript wählt zur Laufzeit einen freien lokalen Port und sendet beispielsweise die folgende Loopback-Redirect-URI an Google.

http://127.0.0.1:54321/callback/

Dies ist der Loopback-Callback, den Google für Desktop-Apps zulässt. https://<worker-host>/callback, https://<worker-host>/mcp und Cloudflare-Access-URLs dürfen nicht als Redirect-URIs des Google-OAuth-Clients registriert werden. Verwenden Sie dieses Skript außerdem nicht mit einem OAuth-Client vom Typ Web application.

python scripts/get_google_refresh_token.py

Sie werden zur Eingabe von GOOGLE_CLIENT_ID und GOOGLE_CLIENT_SECRET aufgefordert. Melden Sie sich im Browser mit dem Google-Konto an, das der Worker verwendet, und genehmigen Sie nur die folgenden Read-only-Scopes.

Wenn Sie die Browser-Genehmigung widerrufen möchten, drücken Sie im wartenden Terminal Ctrl+C. Der lokale Callback-Listener wird geschlossen und das Skript endet, ohne Tokens zu speichern.

• https://www.googleapis.com/auth/analytics.readonly

• https://www.googleapis.com/auth/adsense.readonly

Kopieren Sie die einzige Zeile, die bei Erfolg angezeigt wird, und geben Sie sie in das Feld für das Secret GOOGLE_REFRESH_TOKEN des Deploy-Buttons oder in den folgenden interaktiven Befehl ein.

pnpm wrangler secret put GOOGLE_REFRESH_TOKEN

Falls Client-ID und -Secret ebenfalls nicht gesetzt sind, konfigurieren Sie diese auf die gleiche Weise.

pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET

Wenn der Google-OAuth-Zustimmungsbildschirm weiterhin auf External + Testing steht, läuft das Refresh-Token normalerweise nach 7 Tagen ab. Migrieren Sie vor der dauerhaften Nutzung zu Production und schließen Sie die von Google geforderte Verifizierung ab. Wenn invalid_grant auftritt, widerrufen Sie den Zugriff dieser App im Google-Konto, führen Sie das Skript erneut aus und aktualisieren Sie das Worker-Secret.

Lokale Entwicklung

Erforderlich: Node.js 20 oder höher, Corepack und ein Cloudflare-Konto, das Cloudflare Zero Trust verwenden kann.

corepack enable
pnpm install
Copy-Item .dev.vars.example .dev.vars
pnpm check
pnpm dev --local

Legen Sie die echten Google-Anmeldedaten in .dev.vars ab. Diese Datei wird nicht zu Git hinzugefügt.

Deployment auf Cloudflare

1. Ändern Sie in wrangler.jsonc den name, CF_ACCESS_TEAM_DOMAIN und CF_ACCESS_AUD auf Ihre Cloudflare-Access-Konfigurationswerte.

2. Legen Sie die Secrets einzeln fest.

pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET
pnpm wrangler secret put GOOGLE_REFRESH_TOKEN
pnpm run deploy

3. Erstellen Sie im Cloudflare Zero Trust Dashboard eine MCP server application für https://<worker-host>/mcp des Workers.

4. Erstellen Sie eine Access Policy für zulässige E-Mail-Adressen oder ID-Gruppen und lehnen Sie nicht berechtigte Benutzer ab.

5. Aktivieren Sie unter Advanced settings Managed OAuth. Stellen Sie sicher, dass das Application-Audience-Tag und die Team Domain mit den Worker-Einstellungen übereinstimmen.

Cloudflare Access übernimmt die OAuth-Discovery, die Dynamic Client Registration, den Authorization Code Flow, PKCE und die Erneuerung von Access-Tokens. Fügen Sie im Worker keine eigenen /authorize-, /token- oder /register-Endpunkte hinzu.

Verbindung mit MCP-Clients

Der MCP-Endpunkt ist https://<worker-host>/mcp. Beim ersten Verbindungsaufbau öffnet sich der Cloudflare-Access-Login und die Autorisierung.

• Inspector: Starten Sie npx @modelcontextprotocol/inspector@latest, verbinden Sie den Endpunkt und scannen Sie alle Tools mit Scan / List Tools.

• Codex usw.: Registrieren Sie den Endpunkt in einer OAuth-fähigen Remote-MCP-Konfiguration.

• ChatGPT: Registrieren Sie den Endpunkt in einer Custom-MCP-App bzw. einem Connector im Developer-Modus, schließen Sie die OAuth-Autorisierung ab und führen Sie dann den Tool-Scan aus. Die Verfügbarkeit in ChatGPT hängt vom Vertragsplan, den Workspace-Einstellungen und der Region ab.

Validierung

pnpm check

check führt nacheinander ESLint, TypeScript, Vitest, die Synchronisierung der Worker-Binding-Typen und wrangler deploy --dry-run aus. Anfragen an echte Google-Konten werden nicht automatisch getestet. Führen Sie nach dem Deployment über Access mit dem Inspector und dem verwendeten MCP-Client je einen GA4-Report und einen AdSense-Report aus.

Fehleranalyse der Google API

Bei einem Fehler der Google API gibt der Worker ein JSON-Diagnoseereignis in die Cloudflare Workers Logs aus. Der HTTP-Antworttext von Google, die Anfrage-URL und der Anfragebody sowie Ausnahmename, -meldung und Stacktrace werden ungekürzt ausgegeben. Dies ist eine Debug-Konfiguration, die nur für Log-Leser des Cloudflare-Zielkontos sichtbar ist. Wenn Sie Logs extern übertragen, teilen oder veröffentlichen, deaktivieren Sie diese Detail-Logs vorher. Sie werden weiterhin nicht in die MCP-Antwort aufgenommen.

pnpm wrangler tail --format json

Beispiel: {"event":"google_request_failed","tool":"ga4_run_report","category":"google_api","upstreamStatus":403,"error":{"request":{"url":"..."},"responseBody":"...","stack":"..."}}. oauth_refresh steht für einen Fehler bei der Erneuerung des Refresh-Tokens, google_api für eine Ablehnung durch die GA4-/AdSense-API und unexpected für unerwartete Fehler wie Netzwerkprobleme.

Lizenz

MIT License