mcp-ga4

MCP-Server für Google Analytics 4 – Berichte, Echtzeitdaten, benutzerdefinierte Dimensionen und Property-Verwaltung über Claude ausführen.

Funktionen

• 9 Tools für Berichte, Echtzeitdaten, benutzerdefinierte Dimensionen/Metriken, Datenströme und Feedback

• Zwei Konfigurationsmodi: Einzel-Property (Umgebungsvariablen) und Multi-Client (config.json)

• Unterstützt sowohl Service-Account- als auch OAuth-Anmeldedaten

• Relative Datumsunterstützung (today, yesterday, 7daysAgo, 30daysAgo, 90daysAgo)

• Basiert auf offiziellen Google-SDKs mit Resilienz-Mustern

Related MCP server: Google Analytics 4 MCP Server

Installation

npm install mcp-ga4

Oder klonen Sie das Repository:

git clone https://github.com/mharnett/mcp-ga4.git
cd mcp-ga4
npm install
npm run build

Authentifizierung

mcp-ga4 unterstützt zwei Anmeldedaten-Familien. Die Auswahl ist deterministisch und erfolgt einmalig beim Start: Ein expliziter Schlüsseldatei-/Service-Account gewinnt, dann Benutzer-OAuth, und wenn keiner konfiguriert ist, beendet sich der Server mit einer deutlichen Onboarding-Fehlermeldung, die beide Optionen nennt. Es gibt keinen maschinenlokalen Anmeldedaten-Pfad im Code und kein stilles Laufzeit-Failover – die einzigen Anmeldedaten-Eingaben sind Umgebungsvariablen und (optional) Ihre eigene benutzerspezifische config.json. (Ein späteres 403 erscheint daher als API-Fehler, nicht als stiller Wechsel zur anderen Anmeldedaten-Familie.)

Priorität: Wenn beide Familien konfiguriert sind, hat die Schlüsseldatei-/Service-Account Vorrang vor Benutzer-OAuth.

Option A: Service-Account (empfohlen für unbeaufsichtigten / Server-Einsatz)

Verwenden Sie dies für jeden Dauerbetrieb oder Server-Einsatz. Weisen Sie GOOGLE_APPLICATION_CREDENTIALS (oder config.json credentials_file) auf eine JSON-Schlüsseldatei. Dem Service-Account muss Zugriff auf die GA4-Property gewährt werden (Admin → Property Access Management → fügen Sie die Service-Account-E-Mail mit mindestens Viewer hinzu). Es ist kein Refresh-Token erforderlich – der Server übergibt die Schlüsseldatei direkt an die GA4-SDKs:

GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

Die Schlüsseldatei kann ein echter Service-Account-Schlüssel oder ein authorized_user-OAuth-Token-Dump sein – beide werden über die Option keyFile akzeptiert.

Option B: Benutzer-OAuth (persönliche / interaktive Nutzung)

Verwenden Sie dies, wenn der Server als Google-Benutzer (Ihr eigener GA4-Login) agieren soll. Sie bringen Ihren eigenen Google-OAuth-Client mit und erstellen einmalig ein Refresh-Token.

1. Erstellen Sie in der Google Cloud Console eine OAuth-2.0-Client-ID vom Typ Desktop-App. Aktivieren Sie die Google Analytics Data API (und die Admin API, wenn Sie die Tools für benutzerdefinierte Dimensionen verwenden).

2. Exportieren Sie Ihre Client-Anmeldedaten und führen Sie den Token-Helfer aus (verwendet PKCE, öffnet einen Browser, gibt das Token auf stdout aus):

   export GA4_CLIENT_ID=...            # from the Desktop-app client
   export GA4_CLIENT_SECRET=...
   node get-refresh-token.cjs          # or: npm run auth

   Leiten Sie die stdout dieses Befehls nicht in ein gemeinsames Protokoll um – das Refresh-Token wird dort absichtlich ausgegeben.

3. Kopieren Sie das ausgegebene GA4_REFRESH_TOKEN=... in Ihre Umgebung. Zur Laufzeit liest der Server diese drei Umgebungsvariablen:

   GA4_CLIENT_ID=...
   GA4_CLIENT_SECRET=...
   GA4_REFRESH_TOKEN=...

Der angeforderte Bereich wird aus config.json oauth.scope gelesen (siehe unten), sodass der Helfer und der laufende Server nie darüber uneinig sind, was Sie gewährt haben.

Bereiche (Mindestumfang)

Bereiche befinden sich in config.json unter oauth.scope. Der standardmäßig festgelegte Wert ist:

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

analytics.edit ist erforderlich, da ga4_create_custom_dimension die Property über die Admin API verändert. Wenn Sie nur Lesezugriff benötigen, überschreiben Sie oauth.scope in Ihrer eigenen config.json mit nur analytics.readonly und führen Sie den Helfer erneut aus.

Konfiguration

Sicherheit: Teilen Sie Ihre .mcp.json-Datei niemals und committen Sie sie nicht in Git – sie kann API-Anmeldedaten enthalten. Fügen Sie .mcp.json zu Ihrer .gitignore hinzu.

Modus 1: Einzel-Property (Umgebungsvariablen)

Legen Sie eine Property-ID sowie eine der oben genannten Anmeldedaten-Familien fest:

GA4_PROPERTY_ID=123456789
# then EITHER the OAuth trio (GA4_CLIENT_ID/SECRET/REFRESH_TOKEN)
# OR a service account: GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

Modus 2: Multi-Client (config.json)

Erstellen Sie eine config.json im Projektstamm, um mehrere GA4-Properties auf Projektverzeichnisse abzubilden. Der Server erkennt automatisch, welche Property basierend auf dem Arbeitsverzeichnis des Aufrufers verwendet werden soll. Anmeldedaten stammen aus der Umgebung (Option A/B oben); config.json kann optional einen credentials_file-Service-Account-Pfad für eine reine Konfigurations-SA-Einrichtung enthalten.

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/analytics.readonly https://www.googleapis.com/auth/analytics.edit"
  },
  "clients": {
    "client-a": {
      "name": "Client A",
      "folder": "/path/to/client-a/project",
      "property_id": "123456789"
    },
    "client-b": {
      "name": "Client B",
      "folder": "/path/to/client-b/project",
      "property_id": "987654321"
    }
  }
}

Verwendung

Claude Code (.mcp.json)

Einzel-Property-Modus:

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["mcp-ga4"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

Multi-Client-Modus:

{
  "mcpServers": {
    "ga4": {
      "command": "node",
      "args": ["/path/to/mcp-ga4/dist/index.js"]
    }
  }
}

Claude Desktop: Fügen Sie zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %APPDATA%\Claude\claude_desktop_config.json (Windows) hinzu.

Häufige Abfragemuster

Top-Seiten: dimensions=pagePath, metrics=screenPageViews, order_by=screenPageViews

Verkehrsquellen: dimensions=sessionSource,sessionMedium, metrics=sessions,totalUsers

Täglicher Trend: dimensions=date, metrics=sessions,totalUsers

Kampagnenleistung: dimensions=sessionCampaignName, metrics=sessions,conversions

Geräteaufschlüsselung: dimensions=deviceCategory, metrics=sessions,totalUsers

Tools

Datumsformate

Verwenden Sie YYYY-MM-DD für absolute Daten oder diese relativen Abkürzungen:

• today

• yesterday

• 7daysAgo

• 30daysAgo

• 90daysAgo

Häufige Dimensionen und Metriken

Dimensionen: date, dateHour, eventName, pagePath, pageTitle, sessionSource, sessionMedium, sessionCampaignName, country, city, deviceCategory, browser, operatingSystem, landingPage, pageReferrer, newVsReturning, firstUserSource, firstUserMedium, firstUserCampaignName

Metriken: sessions, totalUsers, newUsers, activeUsers, screenPageViews, eventCount, conversions, engagedSessions, engagementRate, averageSessionDuration, bounceRate, sessionsPerUser, screenPageViewsPerSession, userEngagementDuration

Datenaktualität

• Standardberichte: 24-48 Stunden Verzögerung

• Echtzeitberichte: nur letzte 30 Minuten

Architektur

Basiert auf:

• @google-analytics/data – GA4 Data API für Berichte

• @google-analytics/admin – GA4 Admin API für Property-Verwaltung

• cockatiel – Resilienz (Wiederholung, Schutzschalter)

• pino – strukturierte Protokollierung

Lizenz

MIT

Autor

Erstellt von Mark Harnett / drak-marketing