GA4 MCP Server

Produktionsreifer, mandantenfähiger Google Analytics 4 MCP-Server für Claude.

Dies ist der erste Connector in einer größeren Plattform. Gemeinsame Infrastruktur (Auth, Clients, Google OAuth-Token-Speicherung, Autorisierung, Logging, Fehler) ist wiederverwendbar. GA4-spezifischer Code bleibt unter src/connectors/ga4 und src/mcp/ga4. Behandle dies nicht als monolithisches Google Marketing MCP.

Architektur

Claude
  |  MCP OAuth 2.1 + Streamable HTTP
  v
Next.js / Vercel  (/mcp)
  |-- MCP tools (ga4_*)
  |-- Authorization (client_members only)
  |-- GA4 service
  |-- Google OAuth token manager
  v
Supabase
  |-- clients
  |-- client_members   (application identity)
  |-- google_connections (Google credential, not app identity)
  |-- ga4_properties

Anwendungsbenutzer sind Supabase Auth-Benutzer. Der Mandantenzugriff erfolgt ausschließlich über client_members(user_id, client_id, role). Ein Google-verbundenes Konto ist eine client-eigene Berechtigung und niemals der Anwendungsbenutzer.

Lokale Einrichtung

npm install
cp .env.example .env.local
# fill in the values documented below
npx supabase start   # or link a remote project
npx supabase db reset --local
npm run dev

Öffne http://localhost:3000, erstelle ein Anwendungskonto, erstelle einen Client und verbinde dann Google Analytics.

Google Cloud Einrichtung

1. Erstelle oder wähle ein Google Cloud-Projekt.

2. Aktiviere Google Analytics Data API und Google Analytics Admin API.

3. Konfiguriere den OAuth-Zustimmungsbildschirm (Extern oder Intern).

4. Erstelle OAuth 2.0 Client-ID-Anmeldedaten (Webanwendung).

5. Autorisierte Weiterleitungs-URI:

   • Lokal: http://localhost:3000/api/auth/google/callback

   • Produktion: https://<deine-domain>/api/auth/google/callback

6. Fordere nur GA4-Bereiche an:

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

   • openid

   • email

Füge diesem Connector keine DV360- oder Google Ads-Bereiche hinzu.

GA4 Einrichtung

1. Melde dich bei dieser App mit E-Mail/Passwort an (Anwendungsidentität).

2. Erstelle einen Client (du wirst zum owner in client_members).

3. Füge optional andere Anwendungsbenutzer als owner oder member hinzu.

4. Klicke auf Connect Google Analytics. Dadurch wird eine Google-Berechtigung an den Client gebunden.

5. Verknüpfe eine oder mehrere GA4-Properties, die von diesem Google-Konto entdeckt wurden.

Ein Mitglied, das nicht auf Connect geklickt hat, kann den Client dennoch abfragen, wenn es einen client_members-Eintrag besitzt.

Supabase Einrichtung

Dieses Repository enthält SQL-Migrationen in supabase/migrations. Erstelle sie mit der CLI; erfinde keine Dateinamen.

Lokal:

npx supabase start
npx supabase db reset --local

Remote:

npx supabase link --project-ref <project-ref>
npx supabase db push

Der Service-Rollen-Schlüssel ist nur für den Server bestimmt. Setze niemals SUPABASE_SERVICE_ROLE_KEY oder Google-Refresh-Tokens im Browser offen.

Umgebungsvariablen

Siehe .env.example. Erforderlich:

Setze keine GA4-Property-ID in .env. Properties gehören zu Clients in Supabase.

Generiere einen Token-Verschlüsselungsschlüssel:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

MCP Einrichtung (Claude)

Remote-Endpunkt:

https://<your-domain>/mcp

Dieser Server implementiert MCP OAuth 2.1:

• Geschützte Ressourcen-Metadaten: /.well-known/oauth-protected-resource

• Autorisierungsserver-Metadaten: /.well-known/oauth-authorization-server

• Autorisieren: /oauth/authorize (Anmeldung + Zustimmung)

• Token: /oauth/token (authorization_code + refresh_token, PKCE S256)

• Registrieren: /oauth/register (DCR-Fallback)

• CIMD wird beworben (client_id_metadata_document_supported)

In Claude: Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen → https://<deine-domain>/mcp einfügen. Claude führt OAuth aus. Nach deiner Zustimmung sind die Tools verfügbar.

Lokaler Inspector:

npx @modelcontextprotocol/inspector

Verbinde mit Streamable HTTP zu http://localhost:3000/mcp. Du benötigst weiterhin ein gültiges MCP-Bearer-Token aus dem OAuth-Flow.

Tools

Jedes Tool erfordert client_id. Property-bezogene Tools erfordern außerdem eine verknüpfte property_id. Die Autorisierung prüft immer zuerst client_members, bevor Google aufgerufen wird.

Beispiel: ga4_run_report

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "date_start": "2026-08-01",
  "date_end": "2026-08-15",
  "dimensions": ["country"],
  "metrics": ["activeUsers", "sessions", "totalRevenue"],
  "limit": 10
}

Beispiel: ga4_compare_periods

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "current_start": "2026-08-01",
  "current_end": "2026-08-15",
  "previous_start": "2026-07-17",
  "previous_end": "2026-07-31",
  "metrics": ["activeUsers", "sessions", "totalRevenue"]
}

Claude kann dann Fragen beantworten wie:

• Wie viele Benutzer hatten wir gestern?

• Top 10 Länder diesen Monat

• Vergleiche diesen Monat mit dem letzten Monat

• Wie viele aktive Benutzer sind gerade auf der Seite?

Testen

npm test

Tests verwenden gemocktes Google und Supabase. Sie verwenden niemals Produktions-OAuth-Token.

Vercel

Stelle die Next.js-App bereit und setze die gleichen Umgebungsvariablen. MCP_BASE_URL und GOOGLE_REDIRECT_URI müssen die Produktionsdomain verwenden. Die /mcp-Route läuft auf der Node.js-Laufzeit mit einer maximalen Dauer von 60s.

Projektstruktur

src/
  auth/              application authentication
  authorization/     authorizeClient via client_members
  oauth/             Google OAuth + token manager
  mcp-oauth/         MCP OAuth 2.1 authorization server
  connectors/ga4/    Google Analytics APIs
  mcp/ga4/           MCP tools
  repositories/      Supabase data access
  app/mcp/           Streamable HTTP transport

Zukünftige Connectors (DV360, Google Ads) sollten src/connectors/<name> und src/mcp/<name> hinzufügen und den gemeinsamen Kern wiederverwenden. Erstelle keine allgemeine Google-API-Sammelstelle.