Créer un serveur MCP pour Google Analytics

Un serveur MCP GA4 qui tourne sur votre ordinateur portable, c’est le travail d’un après-midi. Un serveur auquel d’autres personnes peuvent se connecter, c’est un chantier beaucoup plus lourd. Ce guide vous donne la version d’un après-midi, puis liste ce qu’implique la grande, pour que vous choisissiez celle qu’il vous faut.

Table des matières

Regardez d’abord le serveur officiel

Google publie son propre serveur MCP Google Analytics, toujours marqué comme expérimental. Il tourne sur votre ordinateur en Python, et il faut activer la Google Analytics Admin API et la Data API dans un projet Google Cloud avant qu’il fonctionne. Il propose déjà run_report, run_realtime_report, run_funnel_report et des requêtes sur vos comptes, propriétés, dimensions personnalisées et liens Google Ads. Si vous n’avez besoin que de GA4, et seulement sur votre machine, utilisez-le :

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

La page de configuration de Google détaille le projet Cloud, et le README donne la ligne claude mcp add exacte pour Claude Code. Il n’existe pas de version hébergée : il ne fonctionne que là où vous pouvez exécuter Python.

Créez le vôtre quand vous voulez des outils taillés pour vos questions, des données de plusieurs sources dans une seule réponse, ou un serveur que votre équipe ou vos clients peuvent utiliser.

Ce qu’il vous faut

• Un projet Google Cloud avec la Google Analytics Data API activée (cinq minutes).
• Un ID client OAuth de type application de bureau dans ce projet, téléchargé en JSON. C’est le fichier vers lequel pointe --client-id-file.
• Node 22 ou plus récent, ce qu’exige la version actuelle du paquet @google-analytics/data.
• Un accès Lecteur à la propriété GA4, sur le compte Google avec lequel vous allez vous connecter.

Étape 1 : un seul outil qui lance n’importe quel rapport

Commencez avec un seul outil, run_report. Claude connaît déjà les noms des métriques et des dimensions de GA4, donc un outil souple couvre la plupart des questions. Découpez-le en outils plus étroits plus tard, quand vous verrez quelles questions vous posez vraiment.

Préparez le dossier et connectez-vous une fois. La deuxième commande gcloud compte : les API Analytics de Google refusent les identifiants utilisateur qui n’indiquent pas de projet de quota.

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

Enregistrez ensuite ceci sous le nom 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());

Aucune clé dans le fichier. Le client reprend la connexion que gcloud vient d’enregistrer, et chaque appel s’exécute en votre nom, avec votre accès Lecteur.

Étape 2 : ajoutez-le à Claude

Dans Claude Code, une seule commande l’enregistre. Utilisez le chemin complet du fichier. --scope user le rend disponible dans tous vos projets ; sans cette option, il ne se charge que dans le dossier où vous avez lancé la commande :

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

Demandez ensuite : « Pour la propriété 123456789, quels canaux ont généré le plus de sessions avec engagement le mois dernier ? » Claude choisit les métriques, appelle l’outil et vous explique les lignes. Dans Claude Desktop, le même serveur se déclare dans le fichier de configuration ; mon guide pour créer votre premier serveur MCP indique où il se trouve.

Étape 3 : là où ça se complique

Tout ce qui précède s’exécute en votre nom, sur votre machine. Voici ce qui change quand il doit tourner ailleurs :

1. Hébergement et OAuth. claude.ai et l’application mobile ne peuvent pas joindre un serveur installé sur votre portable. Un serveur hébergé a besoin du flux OAuth de MCP, pour que chaque utilisateur se connecte à son propre compte Google, et d’un endroit sûr où stocker leurs refresh tokens.
2. La vérification d’application de Google. analytics.readonly est un scope sensible. Tant que Google n’a pas vérifié votre application, chaque utilisateur voit un avertissement « application non validée » et vous êtes plafonné à 100 utilisateurs. La vérification demande une politique de confidentialité sur votre propre domaine, une vidéo de démonstration de la connexion, une justification écrite pour chaque scope et un examen.
3. Quotas. La Data API décompte des jetons par propriété : 40 000 par heure et 200 000 par jour pour une propriété standard, avec un plafond de 14 000 par heure et par propriété pour chaque projet Cloud, et 10 requêtes simultanées. La plupart des requêtes coûtent 10 jetons ou moins. Les longues périodes, les nombreuses dimensions et les propriétés à fort trafic coûtent davantage, et un agent lance des rapports bien plus vite qu’une personne qui clique dans GA4. Une fois hébergé, chaque appel est décompté sur la part de votre projet : ajoutez returnPropertyQuota: true pour voir ce que coûte chaque requête, mettez en cache ce qui se répète et gardez des rapports courts.

SiteWide prend en charge l’hébergement et la connexion. Sa vérification Google est encore en cours, donc GA4 y affiche pour l’instant le même écran d’application non validée. Si vous préférez ne rien construire de tout cela, connectez plutôt SiteWide.

Demandez à Claude de le créer

Collez ceci dans Claude Code, dans un dossier vide. Le prompt est en anglais, comme le 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.

Avant de vous fier au résultat, vérifiez chaque métrique et chaque dimension utilisée sur la page du schéma de l’API de Google. Un nom inventé passe très bien dans le code et n’échoue qu’au moment où l’API le rejette.