GA4 Analytics MCP

Conector personal de Google Analytics 4 para Conectores personalizados de Claude.ai. Una cuenta de Google, un servidor MCP, desplegado en Vercel.

Claude.ai Custom Connector
  → https://<VERCEL_PROJECT_NAME>.vercel.app/ga4mcp
  → Vercel Streamable HTTP MCP
  → Google Analytics Data API
  → your GA4 properties

No hay servidor local stdio, ni requisito de npx, ni claude_desktop_config.json.

Dos capas de autenticación permanecen separadas:

1. Claude → MCP: OAuth de MCP (CIMD / DCR / cliente opcional de Configuración Avanzada)

2. MCP → Google: Token de actualización de Google OAuth almacenado en GOOGLE_REFRESH_TOKEN

Herramientas MCP

Desarrollo local

npm install
copy .env.example .env.local

Completa .env.local, luego:

npm run dev

• App: http://localhost:3000

• MCP: http://localhost:3000/ga4mcp

• Google OAuth: http://localhost:3000/oauth/google

• Salud: http://localhost:3000/health

npm test
npm run build

Claude.ai no puede alcanzar localhost. Despliega en Vercel antes de agregar el Conector Personalizado.

Configuración de Google Cloud

Esto es solo para que el servidor MCP pueda leer tus datos de GA4. No es el cliente OAuth del conector de Claude.ai.

1. Crea o selecciona un proyecto de Google Cloud.

2. Habilita Google Analytics Data API.

3. Habilita Google Analytics Admin API.

4. Configura la pantalla de consentimiento OAuth (Externa para Gmail personal). Publícala en Producción para que los tokens de actualización no caduquen después de 7 días.

5. Crea un cliente OAuth de Aplicación web.

6. URI de redirección autorizados:

   • http://localhost:3000/oauth/google/callback

   • https://<VERCEL_PROJECT_NAME>.vercel.app/oauth/google/callback

7. Ámbito utilizado por esta aplicación:

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

8. Copia el ID de cliente y el secreto en las variables de entorno.

Luego visita /oauth/google, introduce MCP_AUTH_TOKEN e inicia sesión con la cuenta de Google que posee tus propiedades de GA4.

• Localmente, el token de actualización se escribe en .env.local.

• En Vercel, pega GOOGLE_REFRESH_TOKEN en las variables de entorno del proyecto y vuelve a desplegar.

Variables de entorno

Vercel

npm i -g vercel
vercel
vercel --prod

Agrega las variables de entorno en el proyecto de Vercel. Después del primer Google OAuth en producción, configura GOOGLE_REFRESH_TOKEN y vuelve a desplegar.

Desactiva la Protección de Despliegue / Autenticación de Vercel en producción. Claude.ai se conecta desde la red de Anthropic (160.79.104.0/21). Si el SSO de Vercel está delante de /ga4mcp, el conector no puede conectarse.

URLs de producción:

https://<VERCEL_PROJECT_NAME>.vercel.app/ga4mcp
https://<VERCEL_PROJECT_NAME>.vercel.app/oauth/google/callback
https://<VERCEL_PROJECT_NAME>.vercel.app/health

Un dominio personalizado es opcional más adelante. Sigue usando APP_BASE_URL para que no se requiera ningún cambio de código.

Conector Personalizado de Claude.ai

1. Despliega en Vercel y confirma que https://<VERCEL_PROJECT_NAME>.vercel.app/health devuelve {"status":"ok"}.

2. Conecta Google en https://<VERCEL_PROJECT_NAME>.vercel.app/oauth/google.

3. Pon GOOGLE_REFRESH_TOKEN en las variables de entorno de Vercel y vuelve a desplegar.

4. En Claude.ai abre Personalizar → Conectores → Agregar conector personalizado.

5. Nombre: GA4 Analytics

6. URL:

   https://<VERCEL_PROJECT_NAME>.vercel.app/ga4mcp

7. Deja vacío ID de Cliente OAuth Avanzado / Secreto. Claude usa CIMD contra los endpoints de autorización de este servidor.

8. Haz clic en Agregar.

9. Habilita el conector en el menú + → Conectores del chat.

10. La primera llamada a una herramienta GA4 muestra una tarjeta Conectar. Introduce MCP_AUTH_TOKEN en la página de consentimiento de esta aplicación (no tu contraseña de Google).

11. Pregunta: ¿Cuántos usuarios tuve ayer?

initialize y tools/list son públicos para que Claude pueda descubrir las herramientas. tools/call devuelve HTTP 401 con WWW-Authenticate hasta que se complete el OAuth de MCP.

Seguridad

• Nunca registres tokens de Google, códigos de autorización, secretos de cliente o JWT de MCP.

• Las herramientas MCP nunca devuelven secretos.

• Los tokens de acceso de Google no se almacenan; solo GOOGLE_REFRESH_TOKEN persiste en las variables de entorno.

• No pongas secretos en Git.

Fechas

Se pasan a GA4 sin cambios: today, yesterday, 7daysAgo, 30daysAgo, 90daysAgo o YYYY-MM-DD. La dimensión date devuelve YYYYMMDD.

Limitaciones conocidas

• Una cuenta de Google y un token de actualización.

• Vercel no puede escribir variables de entorno en tiempo de ejecución; pega GOOGLE_REFRESH_TOKEN y vuelve a desplegar.

• Los tokens de actualización en modo de Prueba de Google caducan después de aproximadamente 7 días.

• Los datos en tiempo real son aproximadamente los últimos 30 minutos.

• El tamaño del informe está limitado a 10,000 filas.

• No puedo completar el flujo de clic en vivo de Claude.ai desde este repositorio; eso requiere tus cuentas de Claude y Vercel.