ga4-mcp-worker

Ein schreibgeschützter Google Analytics 4 MCP-Server, der auf Cloudflare Workers läuft, damit Teammitglieder GA4 direkt von Claude abfragen können – ohne dass lokal etwas installiert sein muss: kein Python, kein gcloud, keine ADC-Datei und in dieser Version auch kein gemeinsames Passwort mehr. Das Hinzufügen bedeutet, „Connect“ zu klicken, sich mit dem eigenen Google-Konto anzumelden und GA4-Fragen in der eigenen Identität zu beantworten.

Er übernimmt den Tool-Umfang des offiziellen googleanalytics/google-analytics-mcp-Stdio-Servers, ruft die Google-Analytics-REST-APIs aber direkt auf, weil die Google-Client-Bibliotheken nicht in der Workers-Laufzeit laufen.

Zuerst lesen: docs/IMPLEMENTATION-NOTES.md § Was getestet wurde und was nicht. Die Live-End-to-End-Verifikation ist drin, aber ein paar Oberflächen (die v1alpha-Endpunkte, Pagination) sind weiterhin nur über Fixtures abgedeckt.

Auth-Modus: OAuth pro Benutzer

Jedes Teammitglied meldet sich mit dem eigenen Google-Konto an. Es gibt kein geteiltes Geheimnis und keine einzige Google-Zugangsdauer, auf die sich alle verlassen – siehe PRODUCTION.md § 1 und docs/PRODUCTION-PART2.md § 8 für das vollständige Design und den Unterschied zum ausgemusterten Shared-Secret-Modus. Die Anmeldung ist auf Google-Konten mit @zuddl.com-Domäne beschränkt (ALLOWED_EMAIL_DOMAIN in wrangler.toml).

GOOGLE_CLIENT_ID und GOOGLE_CLIENT_SECRET werden weiterhin benötigt – Google verlangt, dass jede App, die Benutzerdaten anfordert, registriert ist, und genau diese beiden Werte sind die Registrierung. Sie werden einmal beim Deployment gesetzt. Was entfällt, sind das manuell geprägte Refresh-Token und das Passwort, das Teammitglieder früher eingaben.

Dokumentation

Related MCP server: GA4 MCP Server

Unsere GA4-Properties

Der Server ist eigenschaftsagnostischeigentums-agnostisch– jedes Tool nimmt property_id entgegen und akzeptiert 314138239 oder "properties/314138239". Wenn nichts angegeben ist, verwendet er DEFAULT_PROPERTY_ID in wrangler.toml, die auf der kanonischen Property gesetzt ist – so müssen sich Teammitglieder keine Nummer werken. Mit get_account_summaries lässt sich alles auflisten, was die Zugangsdaten tatsächlich lesen können.

Tools (9)

run_report akzeptiert den vollständigen offiziellen Parametersatz: property_id, date_ranges (eine Liste, damit periodenvergleiche in einem Request klappen), dimensions, metrics, dimension_filter, metric_filter, order_bys, limit, offset, currency_code, return_property_quota. run_realtime_report übernimmt die gleiche Form minus date_ranges und currency_code.

Tool-Beschreibungen sind absichtlich lang – sie enthalten konkrete Beispiele für jede Filterform und sind die einzige Stelle, an der das Modell lernt, das Anfrageformat. Behandelt Änderungen an ihr als Verhaltensänderungen.

Endpoints

Alles andere liefert 404.

/health besagt im OAuth-Modus weniger. Es gibt keine einzige geteilte Anmeldedatei, die getestet werden kann. Ein 200 bestätigt nur, dass die App-Registrierung konfiguriert und der Grant-Speicher (OAUTH_KV) erreichbar ist – nicht, dass eine bestimmte Person noch angemeldet ist. Ein einzelner Benutzer-Grant kann abgelaufen oder entzogen sein, während /health „grün“ anzeigt. Das liegt in der Natur der Benutzer-OAuth-Verfahren und ist kein Defekt.

The Worker protokolliert pro MCP-Request, Phase eines abgelehnten Auth-Versuchs, Tool-Fehler, und pro Health-Fehler je eine JSON-Zeile, plus OAuth-spezifische Ereignisse (oauth_authorize_redirect, oauth_authorized, oauth_domain_rejected etc.). Kein Security-Material wird jemals protokolliert. Alle Google-API-Aufrufe senden einen eigenen User-Agent (ga4-mcp-worker/1.0.0 (+cloudflare-workers)) – so Quota-Nutzung eindeutig zugeordnet werden kann.

Read-only-Enforcement:

Vier unabhängige Ebenen, pro Datei vorhanden:

1. OAuth-Scope – jedes Token, egal aus dem alten gemeinsamen oder einem eigenen, wird ausschließlich mit https://www.googleapis.com/auth/analytics.readonly angefordert und sonst nichts (plus openid/email für die Identität im OAuth-Modus – siehe src/google-oauth.ts, gewähren jedoch keinen Einblick in). Google lehnt Schreiboperationen zusätzlich serverseitig sowieso ab. Dies ist die wirkliche Garantie. SETUP-GUIDE.md erklärt, wie man es mit tokeninfo testet.

2. Zulassungsliste Endpunkte – verankerte Regexes, die in den beiden Anker-Helfern vor jedem Netzaufruf geprüft werden. Ein späteres Hinzufügen eines Schreibendpunkts würde eher eine Exception werfen.

3. Keine schreibenden Aktionen – keine PATCH, PUT oder DELETE im gesamten Codebase. Es gibt genau drei Stellen, wo fetch aufgerufen wird: das Token-Minting (POST), gaGet (GET) und gaPost (POST). gibt.

:runReport, :runRealtimeReport und :runFunnelReport sind per HTTP POST und dienen dort als Abfragen – der Body trägt die Unterlagen- oder Definition, weil diese für eine Query–Z zeile zu groß ist. In GA-4 wird nichts erzeugt oder verändert.

Kurzkommandos

npm install

npm run typecheck && npm run dry-run

npm run deploy

npm run tail

curl -s https://ga4-mcp-worker.YOUR-SUBDOMAIN.workers.dev/health

Die fünf Schritte, die beiden Auth-Modi brauchen (Client-seitig und serverseitig):

npx wrangler secret put GOOGLE_CLIENT_ID

npx wrangler secret put GOOGLE_CLIENT_SECRET

Verbindung zu Claude als Client – ohne Header, weil Anmeldung über den Browser läuft:

claude mcp add --transport http --scope user ga4 https://ga4-mcp-worker.YOUR-SUBDOMAIN.workers.dev/mcp

Dann in einer interaktiven claude-Sitzungen: /mcp ausführen, Eintrag ga4 auswählen und mit Google anmelden.

Weiteres

• Fallstricke, Testabdeckung und laufende Kosten: docs/IMPLEMENTATION-NOTES.md

• Erster Deploy-Durchlauf: SETUP-GUIDE.md → Teil 2

• Hardening, Monitoring und das OAuth-Runbook: PRODUCTION.md → Teil 2