GA4 MCP Server

Servidor MCP de Google Analytics 4 listo para producción y multiinquilino para Claude.

Este es el primer conector de una plataforma más grande. La infraestructura compartida (autenticación, clientes, almacenamiento de tokens de Google OAuth, autorización, registro, errores) es reutilizable. El código específico de GA4 permanece en src/connectors/ga4 y src/mcp/ga4. No trates esto como un MCP monolítico de Google Marketing.

Arquitectura

Claude
  |  MCP OAuth 2.1 + Streamable HTTP
  v
Next.js / Vercel  (/mcp)
  |-- MCP tools (ga4_*)
  |-- Authorization (client_members only)
  |-- GA4 service
  |-- Google OAuth token manager
  v
Supabase
  |-- clients
  |-- client_members   (application identity)
  |-- google_connections (Google credential, not app identity)
  |-- ga4_properties

Los usuarios de la aplicación son usuarios de Supabase Auth. El acceso a los inquilinos es solo client_members(user_id, client_id, role). Una cuenta conectada a Google es una credencial propiedad del cliente y nunca es el usuario de la aplicación.

Configuración local

npm install
cp .env.example .env.local
# fill in the values documented below
npx supabase start   # or link a remote project
npx supabase db reset --local
npm run dev

Abre http://localhost:3000, crea una cuenta de aplicación, crea un cliente y luego conecta Google Analytics.

Configuración de Google Cloud

1. Crea o selecciona un proyecto de Google Cloud.

2. Habilita la API de datos de Google Analytics y la API de administración de Google Analytics.

3. Configura la pantalla de consentimiento de OAuth (Externa o Interna).

4. Crea credenciales de ID de cliente de OAuth 2.0 (aplicación web).

5. URI de redirección autorizada:

   • Local: http://localhost:3000/api/auth/google/callback

   • Producción: https://<your-domain>/api/auth/google/callback

6. Solicita solo los ámbitos de GA4:

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

   • openid

   • email

No agregues ámbitos de DV360 o Google Ads a este conector.

Configuración de GA4

1. Inicia sesión en esta aplicación con correo electrónico/contraseña (identidad de la aplicación).

2. Crea un cliente (te conviertes en owner en client_members).

3. Opcionalmente, agrega otros usuarios de la aplicación como owner o member.

4. Haz clic en Conectar Google Analytics. Esto adjunta una credencial de Google al cliente.

5. Vincula una o más propiedades de GA4 descubiertas desde esa cuenta de Google.

Un miembro que no hizo clic en Conectar aún puede consultar al cliente si tiene una fila en client_members.

Configuración de Supabase

Este repositorio incluye migraciones SQL en supabase/migrations. Créalas con la CLI; no inventes nombres de archivo.

Local:

npx supabase start
npx supabase db reset --local

Remoto:

npx supabase link --project-ref <project-ref>
npx supabase db push

La clave de rol de servicio es solo para el servidor. Nunca expongas SUPABASE_SERVICE_ROLE_KEY ni los tokens de actualización de Google al navegador.

Variables de entorno

Consulta .env.example. Requeridas:

No pongas un ID de propiedad de GA4 en .env. Las propiedades pertenecen a los clientes en Supabase.

Genera una clave de cifrado de tokens:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Configuración de MCP (Claude)

Endpoint remoto:

https://<your-domain>/mcp

Este servidor implementa MCP OAuth 2.1:

• Metadatos de recurso protegido: /.well-known/oauth-protected-resource

• Metadatos del servidor de autorización: /.well-known/oauth-authorization-server

• Autorizar: /oauth/authorize (inicio de sesión de la aplicación + consentimiento)

• Token: /oauth/token (authorization_code + refresh_token, PKCE S256)

• Registrar: /oauth/register (respaldo de DCR)

• Se anuncia CIMD (client_id_metadata_document_supported)

En Claude: Configuración → Conectores → Agregar conector personalizado → pega https://<your-domain>/mcp. Claude ejecutará OAuth. Después de que apruebes, las herramientas estarán disponibles.

Inspector local:

npx @modelcontextprotocol/inspector

Conéctate con Streamable HTTP a http://localhost:3000/mcp. Aún necesitas un token Bearer de MCP válido del flujo OAuth.

Herramientas

Cada herramienta requiere client_id. Las herramientas con ámbito de propiedad también requieren un property_id vinculado. La autorización siempre verifica client_members antes de llamar a Google.

Ejemplo: ga4_run_report

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "date_start": "2026-08-01",
  "date_end": "2026-08-15",
  "dimensions": ["country"],
  "metrics": ["activeUsers", "sessions", "totalRevenue"],
  "limit": 10
}

Ejemplo: ga4_compare_periods

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "current_start": "2026-08-01",
  "current_end": "2026-08-15",
  "previous_start": "2026-07-17",
  "previous_end": "2026-07-31",
  "metrics": ["activeUsers", "sessions", "totalRevenue"]
}

Claude puede entonces responder preguntas como:

• ¿Cuántos usuarios tuvimos ayer?

• Top 10 países este mes

• Compara este mes con el mes pasado

• ¿Cuántos usuarios activos hay en el sitio ahora mismo?

Pruebas

npm test

Las pruebas usan Google y Supabase simulados. Nunca usan tokens de OAuth de producción.

Vercel

Despliega la aplicación Next.js y establece las mismas variables de entorno. MCP_BASE_URL y GOOGLE_REDIRECT_URI deben usar el dominio de producción. La ruta /mcp se ejecuta en el tiempo de ejecución de Node.js con una duración máxima de 60 s.

Estructura del proyecto

src/
  auth/              application authentication
  authorization/     authorizeClient via client_members
  oauth/             Google OAuth + token manager
  mcp-oauth/         MCP OAuth 2.1 authorization server
  connectors/ga4/    Google Analytics APIs
  mcp/ga4/           MCP tools
  repositories/      Supabase data access
  app/mcp/           Streamable HTTP transport

Los conectores futuros (DV360, Google Ads) deben agregar src/connectors/<name> y src/mcp/<name> y reutilizar el núcleo compartido. No crees un vertedero genérico de API de Google.