GA4 Analytics MCP

Persönlicher Google Analytics 4 Connector für Claude.ai Custom Connectors, gehostet auf Google Cloud Run.

Claude.ai Custom Connector
  → https://ga4-mcp-xxxxx-uc.a.run.app/ga4mcp
  → Cloud Run
  → Google Analytics Data API
  → your GA4 properties

Es gibt keinen lokalen stdio-Server, keine npx-Anforderung und keine claude_desktop_config.json.

Zwei Authentifizierungsebenen bleiben getrennt:

1. Claude → MCP: MCP OAuth (CIMD / DCR)

2. MCP → Google: Google OAuth Refresh Token, gespeichert in GOOGLE_REFRESH_TOKEN

MCP-Tools

Related MCP server: Google Analytics MCP Server

Lokale Entwicklung

npm install
copy .env.example .env.local

.env.local ausfüllen, dann:

npm run dev

• App: http://localhost:3000

• MCP: http://localhost:3000/ga4mcp

• Google OAuth: http://localhost:3000/oauth/google

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

npm test
npm run build

Claude.ai kann localhost nicht erreichen. Vor dem Hinzufügen des Custom Connectors auf Cloud Run bereitstellen.

Google Cloud Einrichtung (ein Projekt)

Verwenden Sie dasselbe Google Cloud-Projekt für APIs, OAuth und Cloud Run.

1. Installieren und anmelden

1. Installieren Sie das Google Cloud SDK.

2. Führen Sie aus:

gcloud auth login
gcloud auth application-default login

3. Erstellen oder wählen Sie ein Projekt in der Google Cloud Console.

gcloud config set project YOUR_PROJECT_ID

2. APIs aktivieren

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_PROJECT_ID -Region us-central1

Dies aktiviert:

• Cloud Run

• Cloud Build

• Artifact Registry

• Google Analytics Data API

• Google Analytics Admin API

Oder aktivieren Sie sie in der Console: APIs & Services → Library.

3. OAuth-Zustimmung und Web-Client

Dieser Google OAuth-Client dient nur dazu, dass Cloud Run Ihre GA4-Daten lesen kann. Es ist nicht der Client für die Claude.ai Advanced Settings.

1. Öffnen Sie APIs & Services → OAuth consent screen.

2. Benutzertyp: External für ein persönliches Gmail-Konto.

3. App-Name: GA4 MCP.

4. Fügen Sie sich selbst als Testnutzer hinzu, wenn Sie im Testmodus bleiben.

5. Veröffentlichen Sie auf Production, damit Refresh Tokens nicht nach 7 Tagen ablaufen.

6. Erstellen Sie OAuth client ID-Anmeldedaten.

7. Anwendungstyp: Web application.

8. Autorisierte Weiterleitungs-URIs (beide hinzufügen):

   • http://localhost:3000/oauth/google/callback

   • https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback
     (verwenden Sie die echte Cloud Run-URL nach dem ersten Deployment)

9. Von dieser App verwendeter Bereich:

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

10. Kopieren Sie die Client-ID und das Client-Secret. Committen Sie diese nicht.

Das Google-Konto, das Sie autorisieren, muss bereits Zugriff auf die GA4-Properties haben, die Claude abfragen soll.

Auf Cloud Run bereitstellen

Standard-Service-Name: ga4-mcp. Standard-Region: us-central1.

.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_PROJECT_ID -Region us-central1

Das Skript gibt aus:

https://ga4-mcp-XXXXXXXX-uc.a.run.app
https://ga4-mcp-XXXXXXXX-uc.a.run.app/ga4mcp
https://ga4-mcp-XXXXXXXX-uc.a.run.app/health
https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback

Der Service wird allow unauthenticated bereitgestellt. Das ist erforderlich. Claude.ai verbindet sich von Anthropic (160.79.104.0/21). Die Authentifizierung erfolgt über MCP_AUTH_TOKEN / MCP OAuth, nicht über Cloud Run IAM.

Umgebungsvariablen setzen

.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_PROJECT_ID `
  -AppBaseUrl "https://ga4-mcp-XXXXXXXX-uc.a.run.app" `
  -GoogleClientId "....apps.googleusercontent.com" `
  -GoogleClientSecret "...." `
  -McpAuthToken "a-long-random-string"

Fügen Sie dann die Cloud Run-Callback-URL zum Google OAuth-Client hinzu, falls noch nicht geschehen.

Google verbinden

1. Öffnen Sie https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google

2. Geben Sie MCP_AUTH_TOKEN ein

3. Melden Sie sich mit Ihrem Google-Konto an

4. Kopieren Sie GOOGLE_REFRESH_TOKEN von der Erfolgsseite

5. Setzen Sie ihn und lassen Sie Cloud Run eine neue Revision starten:

.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_PROJECT_ID `
  -AppBaseUrl "https://ga4-mcp-XXXXXXXX-uc.a.run.app" `
  -GoogleClientId "....apps.googleusercontent.com" `
  -GoogleClientSecret "...." `
  -McpAuthToken "a-long-random-string" `
  -GoogleRefreshToken "1//...."

Cloud Run kann keine Umgebungsvariablen aus dem Container heraus schreiben. Gleiche Regel wie bei jedem serverlosen Host.

Service bestätigen

https://ga4-mcp-XXXXXXXX-uc.a.run.app/health

muss zurückgeben:

{"status":"ok"}

Umgebungsvariablen

Setzen Sie diese auf dem Cloud Run-Service. Nicht in Git ablegen.

Optionaler Console-Pfad: Cloud Run → ga4-mcp → Edit & deploy new revision → Variables & secrets.

Claude.ai Custom Connector

1. Bestätigen Sie, dass /health {"status":"ok"} zurückgibt.

2. Schließen Sie Google OAuth ab und setzen Sie GOOGLE_REFRESH_TOKEN.

3. Öffnen Sie in Claude.ai Customize → Connectors → Add custom connector.

4. Name: GA4 Analytics

5. URL:

https://ga4-mcp-XXXXXXXX-uc.a.run.app/ga4mcp

6. Lassen Sie Advanced OAuth Client ID / Secret leer.

7. Klicken Sie auf Add.

8. Aktivieren Sie den Connector unter + → Connectors.

9. Beim ersten GA4-Tool-Aufruf erscheint Connect. Geben Sie MCP_AUTH_TOKEN auf der Zustimmungsseite dieser App ein (nicht Ihr Google-Passwort).

10. Fragen Sie: Wie viele Nutzer hatte ich gestern?

Manuelles gcloud (falls Sie die Skripte nicht verwenden möchten)

gcloud artifacts repositories create ga4-mcp --repository-format=docker --location=us-central1
gcloud builds submit --config cloudbuild.yaml --substitutions=_REGION=us-central1
gcloud run services describe ga4-mcp --region us-central1 --format="value(status.url)"
gcloud run services update ga4-mcp --region us-central1 --update-env-vars APP_BASE_URL=https://...,GOOGLE_CLIENT_ID=...,GOOGLE_CLIENT_SECRET=...,GOOGLE_REDIRECT_URI=https://.../oauth/google/callback,MCP_AUTH_TOKEN=...

Sicherheit

• Protokollieren Sie niemals Google-Tokens, Autorisierungscodes, Client-Secrets oder MCP-JWTs.

• MCP-Tools geben niemals Secrets zurück.

• Nur GOOGLE_REFRESH_TOKEN wird als Cloud Run-Umgebungsvariable gespeichert.

• Der Cloud Run-Ingress ist öffentlich, damit Claude sich verbinden kann. Stellen Sie kein Cloud IAP / IAM-Login vor /ga4mcp.

• Generieren Sie ein langes, zufälliges MCP_AUTH_TOKEN.

Daten

Unverändert an GA4 übergeben: today, yesterday, 7daysAgo, 30daysAgo, 90daysAgo oder YYYY-MM-DD. Die Dimension date wird als YYYYMMDD zurückgegeben.

Bekannte Einschränkungen

• Ein Google-Konto und ein Refresh Token.

• Cloud Run kann keine Datei persistieren oder Umgebungsvariablen zur Laufzeit ändern; setzen Sie GOOGLE_REFRESH_TOKEN und stellen Sie eine neue Revision bereit.

• Google-Testmodus-Refresh-Tokens laufen nach etwa 7 Tagen ab.

• Echtzeitdaten umfassen ungefähr die letzten 30 Minuten.

• Die Berichtsgröße ist auf 10.000 Zeilen begrenzt.

• Kalte Starts können einige Sekunden dauern, wenn min-instances auf 0 gesetzt ist.

Für Cloud Run hinzugefügte Dateien