GA4 Analytics MCP

Conector personal de Google Analytics 4 para Conectores personalizados de Claude.ai, alojado en Google Cloud Run.

Claude.ai Custom Connector
  → https://ga4-mcp-xxxxx-uc.a.run.app/ga4mcp
  → Cloud Run
  → Google Analytics Data API
  → your GA4 properties

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

Dos capas de autenticación se mantienen separadas:

1. Claude → MCP: OAuth de MCP (CIMD / DCR)

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

Herramientas de MCP

Related MCP server: Google Analytics MCP Server

Desarrollo local

npm install
copy .env.example .env.local

Rellena .env.local, luego:

npm run dev

• App: http://localhost:3000

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

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

• Health: http://localhost:3000/health

npm test
npm run build

Claude.ai no puede alcanzar localhost. Despliega en Cloud Run antes de añadir el Conector personalizado.

Configuración de Google Cloud (un proyecto)

Usa el mismo proyecto de Google Cloud para las APIs, OAuth y Cloud Run.

1. Instalar e iniciar sesión

1. Instala el Google Cloud SDK.

2. Ejecuta:

gcloud auth login
gcloud auth application-default login

3. Crea o selecciona un proyecto en Google Cloud Console.

gcloud config set project YOUR_PROJECT_ID

2. Habilitar APIs

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_PROJECT_ID -Region us-central1

Esto habilita:

• Cloud Run

• Cloud Build

• Artifact Registry

• Google Analytics Data API

• Google Analytics Admin API

O habilítalas en la Consola: APIs & Services → Library.

3. Consentimiento de OAuth y cliente web

Este cliente OAuth de Google es solo para que Cloud Run pueda leer tus datos de GA4. No es el cliente de Configuración Avanzada de Claude.ai.

1. Abre APIs & Services → OAuth consent screen.

2. Tipo de usuario: External para una cuenta de Gmail personal.

3. Nombre de la aplicación: GA4 MCP.

4. Añádete como usuario de prueba si permaneces en Testing.

5. Publica en Production para que los tokens de actualización no caduquen después de 7 días.

6. Crea credenciales de OAuth client ID.

7. Tipo de aplicación: Web application.

8. URIs de redirección autorizados (añade ambos):

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

   • https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback
     (usa la URL real de Cloud Run después del primer despliegue)

9. Ámbito utilizado por esta aplicación:

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

10. Copia el client ID y el client secret. No los subas al repositorio.

La cuenta de Google que autorices ya debe tener acceso a las propiedades de GA4 que Claude debe consultar.

Desplegar en Cloud Run

Nombre del servicio por defecto: ga4-mcp. Región por defecto: us-central1.

.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_PROJECT_ID -Region us-central1

El script imprime:

https://ga4-mcp-XXXXXXXX-uc.a.run.app
https://ga4-mcp-XXXXXXXX-uc.a.run.app/ga4mcp
https://ga4-mcp-XXXXXXXX-uc.a.run.app/health
https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google/callback

El servicio se despliega permitiendo acceso sin autenticación. Eso es necesario. Claude.ai se conecta desde Anthropic (160.79.104.0/21). La autenticación es MCP_AUTH_TOKEN / OAuth de MCP, no IAM de Cloud Run.

Establecer variables de entorno

.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_PROJECT_ID `
  -AppBaseUrl "https://ga4-mcp-XXXXXXXX-uc.a.run.app" `
  -GoogleClientId "....apps.googleusercontent.com" `
  -GoogleClientSecret "...." `
  -McpAuthToken "a-long-random-string"

Luego añade la URL de callback de Cloud Run al cliente OAuth de Google si aún no lo has hecho.

Conectar Google

1. Abre https://ga4-mcp-XXXXXXXX-uc.a.run.app/oauth/google

2. Introduce MCP_AUTH_TOKEN

3. Inicia sesión con tu cuenta de Google

4. Copia GOOGLE_REFRESH_TOKEN desde la página de éxito

5. Establécelo y deja que Cloud Run inicie una nueva revisión:

.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_PROJECT_ID `
  -AppBaseUrl "https://ga4-mcp-XXXXXXXX-uc.a.run.app" `
  -GoogleClientId "....apps.googleusercontent.com" `
  -GoogleClientSecret "...." `
  -McpAuthToken "a-long-random-string" `
  -GoogleRefreshToken "1//...."

Cloud Run no puede escribir vars de entorno desde dentro del contenedor. Misma regla que cualquier host serverless.

Confirmar el servicio

https://ga4-mcp-XXXXXXXX-uc.a.run.app/health

debe devolver:

{"status":"ok"}

Variables de entorno

Establécelas en el servicio de Cloud Run. No las pongas en Git.

Ruta opcional en la Consola: Cloud Run → ga4-mcp → Edit & deploy new revision → Variables & secrets.

Conector personalizado de Claude.ai

1. Confirma que /health devuelve {"status":"ok"}.

2. Completa OAuth de Google y establece GOOGLE_REFRESH_TOKEN.

3. En Claude.ai abre Customize → Connectors → Add custom connector.

4. Nombre: GA4 Analytics

5. URL:

https://ga4-mcp-XXXXXXXX-uc.a.run.app/ga4mcp

6. Deja vacío Advanced OAuth Client ID / Secret.

7. Haz clic en Add.

8. Habilita el conector en + → Connectors.

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

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

gcloud manual (si no quieres los scripts)

gcloud artifacts repositories create ga4-mcp --repository-format=docker --location=us-central1
gcloud builds submit --config cloudbuild.yaml --substitutions=_REGION=us-central1
gcloud run services describe ga4-mcp --region us-central1 --format="value(status.url)"
gcloud run services update ga4-mcp --region us-central1 --update-env-vars APP_BASE_URL=https://...,GOOGLE_CLIENT_ID=...,GOOGLE_CLIENT_SECRET=...,GOOGLE_REDIRECT_URI=https://.../oauth/google/callback,MCP_AUTH_TOKEN=...

Seguridad

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

• Las herramientas MCP nunca devuelven secretos.

• Solo se persiste GOOGLE_REFRESH_TOKEN, como variable de entorno de Cloud Run.

• El ingreso de Cloud Run es público para que Claude pueda conectarse. No pongas también un inicio de sesión de Cloud IAP / IAM delante de /ga4mcp.

• Genera un MCP_AUTH_TOKEN largo y aleatorio.

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.

• Cloud Run no puede persistir un archivo ni mutar vars de entorno en tiempo de ejecución; establece GOOGLE_REFRESH_TOKEN y despliega una nueva revisión.

• Los tokens de actualización en modo Testing de Google caducan después de unos 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.

• Los arranques en frío pueden añadir unos segundos cuando min-instances es 0.

Archivos añadidos para Cloud Run