GA4 Analytics MCP V2

Multi-Operator-Connector für Claude Custom Connectors, gehostet auf Google Cloud Run.

Dies ist Version 2. Es handelt sich um eine separate Anwendung zu V1. Verwenden Sie nicht die V1-Secrets, V1-OAuth-Clients, V1-Cloud-Run-Dienste oder V1-Git-Remotes.

Operator A or Operator B
  → same Claude Custom Connector URL
  → https://<v2-host>/mcp
  → MCP OAuth (Claude → V2)
  → Google OAuth (operator's own Google account)
  → operator credentials + active GA4 property in Firestore
  → GA4 Admin / Data APIs

Es gibt keinen lokalen stdio-Server und kein Supabase.

Architektur

Zwei OAuth-Ebenen sind miteinander verknüpft:

1. Claude → V2: MCP OAuth 2.1 (Metadaten der geschützten Ressource, DCR, CIMD, PKCE).

2. V2 → Google: Die Google-Anmeldung erfolgt innerhalb der MCP-Autorisierung. Der sub ist der eindeutige Google-Account-Identifier (sub) im MCP-Zugriffstoken. Die E-Mail-Adresse dient nur zur Anzeige.

Jeder Betreiber hat:

• seinen eigenen verschlüsselten Google-Refresh-Token

• seine eigene zugreifbare GA4-Property-Liste (aus der Google Admin API)

• seine eigene gespeicherte aktive Property

Betreiber A kann weder die Google-Anmeldedaten von Betreiber B verwenden noch eine Property auswählen, auf die Google-Konto A keinen Zugriff hat.

MCP-Werkzeuge

Report-Tools verwenden die gespeicherte Aktive Property, wenn propertyId nicht angegeben wird. Eine übergebene propertyId wird nur akzeptiert, wenn das authentifizierte Google-Konto darauf zugreifen kann, und wird dann zur neuen Aktiven Property.

Lokale Entwicklung

cd D:\MCP_Servers\Ga4McpV2
npm install
copy .env.example .env.local

Fülle .env.local mit V2-Werten aus. Kopiere keine V1-Secrets.

Optionaler Firestore-Emulator:

gcloud emulators firestore start --host-port=localhost:8080

Setze FIRESTORE_EMULATOR_HOST=localhost:8080 und FIRESTORE_PROJECT_ID in .env.local.

npm run dev
npm test
npm run build

• App: http://localhost:3000

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

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

• Google-Redirect: http://localhost:3000/oauth/google/callback

Claude.ai kann localhost nicht erreichen. Stelle V2 auf Cloud Run bereit, bevor du den Custom Connector hinzufügst.

Environment-Variablen

V2 verwendet weder GOOGLE_REFRESH_TOKEN noch MCP_AUTH_TOKEN.

Google-Cloud-Konfiguration

Verwende wenn möglich ein neues Google-Cloud-Projekt. Wenn du ein Projekt mit V1 teilst, erstelle trotzdem einen getrennten Cloud-Run-Dienst, ein eigenes Artifact-Registry-Repo, einen eigenen OAuth-Client und eigene Secrets.

Aktiviere:

• Cloud Run

• Cloud Build

• Artifact Registry

• Firestore

• Secret Manager

• Google Analytics Admin API

• Google Analytics Data API

Vorgeschlagene Ressourcennamen (Platzhalter – ersetze sie durch dein Projekt):

• Cloud-Run-Dienst: ga4-mcp-v2

• Artifact Registry: ga4-mcp-v2

• Firestore collection: operators

Das Cloud-Run-Dienstkonto sollte folgende Berechtigungen haben:

• roles/datastore.user auf der V2-Firestore-Datenbank

• roles/secretmanager.secretAccessor nur auf V2-Secrets

Gewähre dem Dienstkonto nicht Secret-Manager-Admin oder Zugriff auf V1-Secrets.

Google OAuth-Client (nur V2)

Erstelle einen neuen OAuth-Web-Client. Bearbeite nicht den V1-Client.

Zustimmungsbildschirm:

• Benutzertyp: External (oder Internal für nur-Workspace)

• App-Name: z. B. GA4 MCP Connector V2

• Scopes:

  • openid

  • email

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

• Testnutzer hinzufügen, solange der App-Status "Testing" ist

• Veröffentlichung erforderlich für Nicht-Testnutzer, da Analytics-Scope sensibel sind

Autorisierte Redirect-URI:

https://<v2-cloud-run-url>/oauth/google/callback

Lokal:

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

Claude – Custom Connector

1. Starte V1 und setze APP_BASE_URL auf die Cloud-Run-URL.

2. In Claude einen Custom Connector hinzufügen.

3. URL: https://<v2-host>/mcp

4. Jeder Betreiber führt sein eigenes Google Sign-In aus.

5. Wenn das Google-Konto mehrere GA 4-Produkte hat, wählt er eines aus. Diese Auswahl bleibt erhalten, bis er wechselt.

Tester

npm test

• MCP OAuth2-Metadaten, DCR, PKCE und JWT sub-Zuordnung zu Google

• Datenisolation zwischen Betreibern

• Persistente Auswahl von Properties

• Token-Refresh / -Rotation

• Widerrufene Google-Grants

• Überarbeitung von Logs

Für Tests werden keine echten V1-Credentials verwendet.

Deployment (nicht ausführen, bis Sie es anfordern)

Nur als Doku. Die V1-Bereitstellung ist nicht betroffen.

Wichtig: für Produktion Secrets raten:

• Bevorzugt Secret-Manager-Referenzen statt Klartext-Environment-Variablen

• Sicherstellen, dass Firestore im nativen Modus eingerichtet ist

• Redirect-URIs nach dem Deployment anpassen

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_V2_PROJECT_ID
.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_V2_PROJECT_ID
.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_V2_PROJECT_ID `
  -AppBaseUrl https://YOUR_V2_CLOUD_RUN_URL `
  -GoogleClientId YOUR_V2_CLIENT_ID `
  -GoogleClientSecret YOUR_V2_CLIENT_SECRET `
  -McpTokenSecret YOUR_MCP_TOKEN_SECRET `
  -OauthStateSecret YOUR_OAUTH_STATE_SECRET `
  -TokenEncryptionKey YOUR_TOKEN_ENCRYPTION_KEY

Security

• Refresh-Tokens sind mit AES-256-GCM verschlüsselt (Firestore)

• MCP-Tools geben niemals Access-Tokens, Refresh-Tokens oder Authorisation-Codes weiter

• Logs redigieren Tokens, Secrets, Cookies und Services

• Property-IDs werden live über die Google Admin API geprüft

• Bei fehlendem Operator-Kontext lehnt MCP die Anfrage ab

Git

Das Repo ist nur für V2. Der V1-Git-Remote (git@github.com:devopsbrandmirchi/Ga4McpServer.git) darf nicht verwendet werden.