Cómo crear un servidor MCP de Google Analytics

Un servidor MCP de GA4 que corre en tu portátil es trabajo de una tarde. Uno en el que otras personas puedan iniciar sesión es un proyecto mucho más grande. Esta guía te da la versión de una tarde y luego enumera lo que implica la grande, para que decidas cuál necesitas.

Tabla de contenidos

Revisa primero el servidor oficial

Google publica su propio servidor MCP de Google Analytics, todavía marcado como experimental. Corre en tu propio equipo con Python, y antes de que funcione tienes que activar la Google Analytics Admin API y la Data API en un proyecto de Google Cloud. Ya trae run_report, run_realtime_report, run_funnel_report y consultas para tus cuentas, propiedades, dimensiones personalizadas y vínculos con Google Ads. Si solo necesitas GA4, y solo en tu equipo, úsalo:

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 página de configuración de Google te guía con el proyecto de Cloud, y el README trae la línea exacta de claude mcp add para Claude Code. No hay versión alojada, así que solo funciona donde puedas ejecutar Python.

Crea el tuyo cuando quieras herramientas pensadas para tus preguntas, datos de más de una fuente en una sola respuesta, o un servidor que puedan usar tu equipo o tus clientes.

Lo que necesitas

• Un proyecto de Google Cloud con la Google Analytics Data API activada (cinco minutos).
• Un ID de cliente OAuth de tipo app de escritorio en ese proyecto, descargado como JSON. Ese es el archivo al que apunta --client-id-file.
• Node 22 o posterior, que es lo que exige el paquete actual de @google-analytics/data.
• Acceso de lector a la propiedad de GA4, en la cuenta de Google con la que vas a iniciar sesión.

Paso 1: Una herramienta que ejecuta cualquier informe

Empieza con una sola herramienta, run_report. Claude ya conoce los nombres de métricas y dimensiones de GA4, así que una herramienta flexible cubre la mayoría de las preguntas. Divídela en herramientas más específicas después, cuando veas qué preguntas haces de verdad.

Prepara la carpeta e inicia sesión una vez. El segundo comando de gcloud importa: las APIs de Analytics de Google rechazan las credenciales de usuario que no indican un proyecto de cuota.

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

Después guarda esto como 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());

No hay ninguna clave en el archivo. El cliente usa el inicio de sesión que gcloud acaba de guardar, y cada llamada se ejecuta como tú, con tu acceso de lector.

Paso 2: Añádelo a Claude

En Claude Code, un comando lo registra. Usa la ruta completa del archivo. --scope user lo deja disponible en todos tus proyectos; sin esa opción solo se carga en la carpeta donde ejecutaste el comando:

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

Luego pregunta: “Con la propiedad 123456789, ¿qué canales generaron más sesiones con interacción el mes pasado?”. Claude elige las métricas, llama a la herramienta y te explica las filas. En Claude Desktop el mismo servidor va en el archivo de configuración; mi guía para crear tu primer servidor MCP explica dónde está.

Paso 3: Donde se complica

Todo lo anterior se ejecuta como tú, en tu equipo. Esto es lo que cambia cuando tiene que funcionar en cualquier otro sitio:

1. Alojamiento y OAuth. claude.ai y la app móvil no pueden llegar a un servidor que está en tu portátil. Un servidor alojado necesita el flujo OAuth de MCP, para que cada usuario inicie sesión con su propia cuenta de Google, y un lugar seguro donde guardar sus refresh tokens.
2. La verificación de apps de Google. analytics.readonly es un scope sensible. Hasta que Google verifique tu app, cada usuario ve un aviso de “app no verificada” y tienes un límite de 100 usuarios. La verificación exige una política de privacidad en tu propio dominio, un vídeo de demostración del inicio de sesión, una justificación escrita para cada scope y una revisión.
3. Cuotas. La Data API mide tokens por propiedad: 40.000 por hora y 200.000 por día en una propiedad estándar, con un máximo de 14.000 por hora y propiedad para cada proyecto de Cloud y 10 solicitudes a la vez. La mayoría de las solicitudes cuestan 10 tokens o menos. Los rangos de fechas largos, muchas dimensiones y las propiedades con mucho tráfico cuestan más, y un agente lanza informes mucho más rápido que una persona navegando por GA4. Alojado, cada llamada sale de la cuota de tu proyecto, así que añade returnPropertyQuota: true para ver lo que cuesta cada solicitud, guarda en caché lo que se repite y mantén los informes pequeños.

SiteWide se encarga del alojamiento y del inicio de sesión. Su verificación con Google sigue en curso, así que por ahora GA4 muestra ahí también la misma pantalla de app no verificada. Si prefieres no crear nada de esto, conecta SiteWide.

Pídele a Claude que lo cree

Pega esto en Claude Code, en una carpeta vacía. El prompt está en inglés porque el código también lo está:

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.

Antes de fiarte del resultado, comprueba cada métrica y dimensión que use en la página del esquema de la API de Google. Un nombre inventado se ve bien en el código y solo falla cuando la API lo rechaza.