Einen Google Analytics MCP-Server bauen

Ein GA4-MCP-Server, der auf deinem Laptop läuft, ist ein Nachmittag Arbeit. Einer, bei dem sich andere Leute anmelden können, ist ein deutlich größeres Projekt. Diese Anleitung gibt dir die Nachmittagsversion und zählt dann auf, was die große Version mit sich bringt, damit du entscheiden kannst, welche du brauchst.

Inhaltsverzeichnis

Prüf zuerst den offiziellen Server

Google veröffentlicht einen eigenen Google Analytics MCP-Server, der noch als experimentell gekennzeichnet ist. Er läuft in Python auf deinem eigenen Rechner, und bevor er funktioniert, aktivierst du die Google Analytics Admin API und die Data API in einem Google-Cloud-Projekt. Er bringt bereits run_report, run_realtime_report, run_funnel_report und Abfragen für deine Konten, Properties, benutzerdefinierten Dimensionen und Google-Ads-Verknüpfungen mit. Wenn du nur GA4 brauchst, und nur auf deinem Rechner, nimm ihn:

gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=YOUR_CLIENT_JSON_FILE

pipx run analytics-mcp

Googles Einrichtungsseite führt durch das Cloud-Projekt, und im README steht die genaue claude mcp add-Zeile für Claude Code. Eine gehostete Version gibt es nicht, er läuft also nur dort, wo du Python ausführen kannst.

Bau deinen eigenen, wenn du Tools willst, die auf deine Fragen zugeschnitten sind, Daten aus mehr als einer Quelle in einer Antwort, oder einen Server, den dein Team oder deine Kunden nutzen können.

Was du brauchst

• Ein Google-Cloud-Projekt mit aktivierter Google Analytics Data API (fünf Minuten).
• Eine OAuth-Client-ID vom Typ Desktop-App in diesem Projekt, als JSON heruntergeladen. Auf diese Datei zeigt --client-id-file.
• Node 22 oder neuer, das verlangt das aktuelle Paket @google-analytics/data.
• Betrachter-Zugriff auf die GA4-Property, mit dem Google-Konto, mit dem du dich anmeldest.

Schritt 1: Ein Tool, das jeden Bericht ausführt

Fang mit einem einzigen Tool an, run_report. Claude kennt die Namen der GA4-Messwerte und -Dimensionen bereits, deshalb deckt ein flexibles Tool die meisten Fragen ab. Teil es später in engere Tools auf, wenn du siehst, welche Fragen du wirklich stellst.

Leg den Ordner an und melde dich einmal an. Der zweite gcloud-Befehl ist wichtig: Googles Analytics-APIs lehnen Nutzer-Anmeldedaten ab, die kein Kontingentprojekt angeben.

mkdir ga4-mcp && cd ga4-mcp
npm init -y && npm pkg set type=module
npm install @modelcontextprotocol/sdk @google-analytics/data zod

gcloud auth application-default login \
  --scopes https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=YOUR_CLIENT_JSON_FILE
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Speichere dann das hier als ga4.ts:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { BetaAnalyticsDataClient } from '@google-analytics/data';
import { z } from 'zod';

const ga = new BetaAnalyticsDataClient(); // Application Default Credentials
const server = new McpServer({ name: 'ga4', version: '1.0.0' });

server.registerTool(
  'run_report',
  {
    description:
      'Run a GA4 report. Uses GA4 Data API metric and dimension names. ' +
      'Dates accept YYYY-MM-DD, "28daysAgo", "yesterday", "today".',
    inputSchema: {
      propertyId: z.string().describe('Numeric GA4 property ID, e.g. 123456789'),
      metrics: z.array(z.string()).describe('e.g. ["sessions", "engagedSessions"]'),
      dimensions: z.array(z.string()).default([]).describe('e.g. ["sessionDefaultChannelGroup"]'),
      startDate: z.string().default('28daysAgo'),
      endDate: z.string().default('today'),
    },
  },
  async ({ propertyId, metrics, dimensions, startDate, endDate }) => {
    const [res] = await ga.runReport({
      property: `properties/${propertyId}`,
      dateRanges: [{ startDate, endDate }],
      metrics: metrics.map((name) => ({ name })),
      dimensions: dimensions.map((name) => ({ name })),
      limit: 100,
    });
    // Turn GA's nested rows into plain { dimension: value, metric: value } objects.
    const rows = (res.rows ?? []).map((row) => {
      const out: Record<string, string> = {};
      row.dimensionValues?.forEach((v, i) => (out[dimensions[i]] = v.value ?? ''));
      row.metricValues?.forEach((v, i) => (out[metrics[i]] = v.value ?? ''));
      return out;
    });
    return { content: [{ type: 'text', text: JSON.stringify({ rowCount: res.rowCount, rows }) }] };
  },
);

await server.connect(new StdioServerTransport());

In der Datei steht kein Schlüssel. Der Client übernimmt die Anmeldung, die gcloud gerade gespeichert hat, und jeder Aufruf läuft unter deinem Konto, mit deinem Betrachter-Zugriff.

Schritt 2: In Claude einbinden

In Claude Code registriert ihn ein einziger Befehl. Gib den vollständigen Pfad zur Datei an. Mit --scope user steht er in allen Projekten zur Verfügung; ohne die Option lädt er nur in dem Ordner, in dem du den Befehl ausgeführt hast:

claude mcp add --scope user ga4 -- npx -y tsx /full/path/to/ga4-mcp/ga4.ts

Dann frag: „Welche Kanäle haben in Property 123456789 letzten Monat die meisten Sitzungen mit Interaktion gebracht?“ Claude wählt die Messwerte, ruft das Tool auf und erklärt die Zeilen. In Claude Desktop kommt derselbe Server stattdessen in die Konfigurationsdatei; meine Anleitung für den ersten MCP-Server zeigt, wo die liegt.

Schritt 3: Wo es schwierig wird

Alles bisher läuft unter deinem Konto, auf deinem Rechner. Das ändert sich, sobald er woanders laufen muss:

1. Hosting und OAuth. claude.ai und die mobile App erreichen keinen Server auf deinem Laptop. Ein gehosteter Server braucht den OAuth-Flow von MCP, damit sich jeder Nutzer mit seinem eigenen Google-Konto anmeldet, und einen sicheren Ort für deren Refresh-Tokens.
2. Googles App-Verifizierung. analytics.readonly ist ein sensibler Scope. Bis Google deine App verifiziert, sieht jeder Nutzer eine Warnung „App nicht überprüft“, und du bist auf 100 Nutzer begrenzt. Die Verifizierung verlangt eine Datenschutzerklärung auf deiner eigenen Domain, ein Demovideo der Anmeldung, eine schriftliche Begründung für jeden Scope und eine Prüfung.
3. Kontingente. Die Data API zählt Tokens pro Property: 40.000 pro Stunde und 200.000 pro Tag bei einer Standard-Property, wobei jedes Cloud-Projekt höchstens 14.000 pro Stunde und Property nutzen darf, bei 10 gleichzeitigen Anfragen. Die meisten Anfragen kosten 10 Tokens oder weniger. Lange Zeiträume, viele Dimensionen und Properties mit viel Traffic kosten mehr, und ein Agent feuert Berichte viel schneller ab als ein Mensch, der sich durch GA4 klickt. Gehostet geht jeder Aufruf vom Anteil deines Projekts ab. Setz deshalb returnPropertyQuota: true, um zu sehen, was jede Anfrage kostet, cache, was sich wiederholt, und halte Berichte klein.

SiteWide übernimmt das Hosting und die Anmeldung. Die Google-Verifizierung läuft noch, deshalb zeigt GA4 dort vorerst denselben Bildschirm „App nicht überprüft“. Wenn du nichts davon selbst bauen willst, verbinde stattdessen SiteWide.

Lass Claude ihn bauen

Füg das in Claude Code in einem leeren Ordner ein. Der Prompt ist auf Englisch, wie der Code:

Build me a TypeScript MCP server for Google Analytics 4 using @modelcontextprotocol/sdk and @google-analytics/data. Give it one tool, run_report, that takes a property id, metrics, dimensions and a date range. Authenticate with Application Default Credentials. Then give me the exact gcloud command to log in with the analytics.readonly scope, and register the server with `claude mcp add`. Don't invent metric names: link me to Google's API schema page so I can check them.

Bevor du dem Ergebnis traust, prüf jeden Messwert und jede Dimension auf Googles API-Schema-Seite. Ein erfundener Name sieht im Code gut aus und scheitert erst, wenn die API ihn ablehnt.