Een Google Analytics MCP-server bouwen

Een GA4 MCP-server die op je laptop draait, is een middag werk. Eén waarop andere mensen kunnen inloggen, is een veel groter project. Deze gids geeft je de middagversie en zet daarna op een rij wat de grote versie inhoudt, zodat je kunt kiezen welke je nodig hebt.

Inhoudsopgave

Kijk eerst naar de officiële server

Google publiceert een eigen Google Analytics MCP-server, nog steeds gemarkeerd als experimenteel. Hij draait in Python op je eigen computer, en voordat hij werkt zet je de Google Analytics Admin API en de Data API aan in een Google Cloud-project. Hij heeft al run_report, run_realtime_report, run_funnel_report en opvragingen voor je accounts, property’s, aangepaste dimensies en Google Ads-koppelingen. Heb je alleen GA4 nodig, en alleen op je eigen computer, gebruik hem dan:

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 installatiepagina loopt het Cloud-project met je door, en de README bevat de exacte claude mcp add-regel voor Claude Code. Er is geen gehoste versie, dus hij werkt alleen waar je Python kunt draaien.

Bouw je eigen server als je tools wilt die passen bij jouw vragen, data uit meer dan één bron in één antwoord, of een server die je team of je klanten kunnen gebruiken.

Wat je nodig hebt

• Een Google Cloud-project met de Google Analytics Data API ingeschakeld (vijf minuten).
• Een OAuth-client-ID van het type desktop-app in dat project, gedownload als JSON. Dat is het bestand waar --client-id-file naar verwijst.
• Node 22 of nieuwer, wat het huidige pakket @google-analytics/data vereist.
• Kijkerstoegang tot de GA4-property, op het Google-account waarmee je inlogt.

Stap 1: één tool die elk rapport draait

Begin met één tool, run_report. Claude kent de namen van de statistieken en dimensies van GA4 al, dus één flexibele tool dekt de meeste vragen. Splits hem later op in specifiekere tools, als je ziet welke vragen je echt stelt.

Zet de map klaar en log één keer in. Het tweede gcloud-commando doet ertoe: Googles Analytics-API’s weigeren gebruikersgegevens zonder quotaproject.

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

Sla dit daarna op 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());

Er staat geen sleutel in het bestand. De client gebruikt de login die gcloud net heeft opgeslagen, en elke aanroep draait als jij, met jouw kijkerstoegang.

Stap 2: voeg hem toe aan Claude

In Claude Code registreert één commando hem. Gebruik het volledige pad naar het bestand. Met --scope user is hij in al je projecten beschikbaar; zonder die optie laadt hij alleen in de map waar je het commando uitvoerde:

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

Vraag dan: “Welke kanalen leverden in property 123456789 vorige maand de meeste sessies met betrokkenheid op?” Claude kiest de statistieken, roept de tool aan en legt de rijen uit. In Claude Desktop gaat dezelfde server in het configuratiebestand; mijn gids voor je eerste MCP-server laat zien waar dat staat.

Stap 3: waar het lastig wordt

Alles hierboven draait als jij, op je eigen computer. Dit verandert er als hij ergens anders moet draaien:

1. Hosting en OAuth. claude.ai en de mobiele app kunnen geen server op je laptop bereiken. Een gehoste server heeft de OAuth-flow van MCP nodig, zodat elke gebruiker inlogt op zijn eigen Google-account, plus een veilige plek om hun refresh tokens te bewaren.
2. Googles app-verificatie. analytics.readonly is een gevoelige scope. Tot Google je app verifieert, ziet elke gebruiker een waarschuwing “niet-geverifieerde app” en zit je aan een limiet van 100 gebruikers. Verificatie vraagt om een privacybeleid op je eigen domein, een demovideo van het inloggen, een schriftelijke onderbouwing per scope en een beoordeling.
3. Quota. De Data API telt tokens per property: 40.000 per uur en 200.000 per dag voor een standaardproperty, waarbij elk Cloud-project maximaal 14.000 per uur per property mag gebruiken, met 10 gelijktijdige verzoeken. De meeste verzoeken kosten 10 tokens of minder. Lange periodes, veel dimensies en property’s met veel verkeer kosten meer, en een agent vuurt rapporten veel sneller af dan iemand die door GA4 klikt. Gehost gaat elke aanroep af van het aandeel van jouw project, dus voeg returnPropertyQuota: true toe om te zien wat elk verzoek kost, cache wat terugkomt en houd rapporten klein.

SiteWide regelt de hosting en het inloggen. De verificatie bij Google loopt nog, dus GA4 toont daar voorlopig hetzelfde scherm voor een niet-geverifieerde app. Wil je dit liever niet zelf bouwen, koppel dan SiteWide.

Laat Claude hem bouwen

Plak dit in Claude Code, in een lege map. De prompt is in het Engels, net als de 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.

Controleer voordat je het resultaat vertrouwt elke statistiek en dimensie op Googles API-schemapagina. Een verzonnen naam ziet er in de code prima uit en faalt pas als de API hem weigert.