GA4 Analytics MCP V2

Conector multioperador de Google Analytics 4 para Claude.ai Custom Connectors, alojado en Google Cloud Run.

Esta es la versión 2. Es una aplicación independiente de V1. No reutilices los secretos, los clientes OAuth, los servicios de Cloud Run ni los remotos de Git de V1.

Operator A or Operator B
  → same Claude Custom Connector URL
  → https://<v2-host>/mcp
  → MCP OAuth (Claude → V2)
  → Google OAuth (operator's own Google account)
  → operator credentials + active GA4 property in Firestore
  → GA4 Admin / Data APIs

No hay ningún servidor stdio local ni Supabase.

Arquitectura

Hay dos capas OAuth vinculadas:

1. Claude → V2: MCP OAuth 2.1 (metadatos de recurso protegido, DCR, CIMD, PKCE).

2. V2 → Google: el inicio de sesión de Google ocurre dentro de la autorización MCP. El sub del token de acceso MCP es el sujeto (sub) de la cuenta de Google. El correo electrónico es solo informativo.

Cada operador tiene:

• su propio token de actualización de Google cifrado

• su propia lista de propiedades GA4 accesibles (de la API de administración de Google)

• su propia propiedad activa persistida

El operador A no puede usar la credencial de Google del operador B ni seleccionar una propiedad a la que la cuenta de Google A no pueda acceder.

Herramientas MCP

Las herramientas de informes usan la propiedad activa almacenada cuando se omite propertyId. Un propertyId proporcionado solo se acepta si la cuenta de Google autenticada puede acceder a él y, en ese caso, se convierte en la nueva propiedad activa.

Desarrollo local

cd D:\MCP_Servers\Ga4McpV2
npm install
copy .env.example .env.local

Rellena .env.local con valores de V2. No copies secretos de V1.

Emulador de Firestore opcional:

gcloud emulators firestore start --host-port=localhost:8080

Establece FIRESTORE_EMULATOR_HOST=localhost:8080 y FIRESTORE_PROJECT_ID en .env.local.

npm run dev
npm test
npm run build

• App: http://localhost:3000

• MCP: http://localhost:3000/mcp

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

• Callback de Google: http://localhost:3000/oauth/google/callback

Claude.ai no puede acceder a localhost. Despliega V2 en Cloud Run antes de añadir el Custom Connector.

Variables de entorno

V2 no usa GOOGLE_REFRESH_TOKEN ni MCP_AUTH_TOKEN.

Configuración de Google Cloud

Usa un proyecto nuevo de Google Cloud cuando sea posible. Si compartes un proyecto con V1, crea igualmente un servicio de Cloud Run, un repositorio de Artifact Registry, un cliente OAuth y secretos distintos.

Habilita:

• Cloud Run

• Cloud Build

• Artifact Registry

• Firestore

• Secret Manager

• Google Analytics Admin API

• Google Analytics Data API

Nombres de recursos sugeridos (marcadores de posición — sustitúyelos por los de tu proyecto):

• Servicio de Cloud Run: ga4-mcp-v2

• Artifact Registry: ga4-mcp-v2

• Colección de Firestore: operators

La cuenta de servicio de Cloud Run debe tener:

• roles/datastore.user en la base de datos de Firestore de V2

• roles/secretmanager.secretAccessor solo en los secretos de V2

No concedas a la cuenta de servicio el rol de administrador de Secret Manager ni acceso a los secretos de V1.

Cliente OAuth de Google (solo V2)

Crea una aplicación web OAuth nueva. No edites el cliente de V1.

Pantalla de consentimiento:

• Tipo de usuario: Externo (o Interno para uso exclusivo de Workspace)

• Nombre de la aplicación: algo como GA4 MCP Connector V2

• Ámbitos:

  • openid

  • email

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

• Añade usuarios de prueba mientras la aplicación esté en modo de pruebas

• La publicación es obligatoria para los usuarios que no sean de prueba porque los ámbitos de Analytics son sensibles

URI de redirección autorizada:

https://<v2-cloud-run-url>/oauth/google/callback

Localmente:

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

Custom Connector de Claude

1. Despliega V2 y establece APP_BASE_URL como la URL de Cloud Run.

2. En Claude, añade un Custom Connector.

3. URL: https://<v2-host>/mcp

4. Cada operador completa el inicio de sesión de Google desde su propia cuenta de Claude.

5. Si la cuenta de Google tiene varias propiedades GA4, elige una. Esa elección persiste hasta que la cambie.

Pruebas

npm test

Las pruebas unitarias cubren:

• Metadatos OAuth de MCP, DCR, PKCE y sub del JWT vinculado a Google

• Aislamiento de operadores (credenciales y listas de propiedades permitidas)

• Propiedad activa persistente

• Actualización / rotación de tokens

• Concesiones de Google revocadas

• Redacción de registros estructurados

No se usan credenciales V1 reales.

Despliegue (no ejecutar hasta que se solicite)

Solo documentado. El despliegue de V1 debe permanecer intacto.

.\scripts\cloud-run-setup.ps1 -ProjectId YOUR_V2_PROJECT_ID
.\scripts\cloud-run-deploy.ps1 -ProjectId YOUR_V2_PROJECT_ID
.\scripts\cloud-run-set-env.ps1 `
  -ProjectId YOUR_V2_PROJECT_ID `
  -AppBaseUrl https://YOUR_V2_CLOUD_RUN_URL `
  -GoogleClientId YOUR_V2_CLIENT_ID `
  -GoogleClientSecret YOUR_V2_CLIENT_SECRET `
  -McpTokenSecret YOUR_MCP_TOKEN_SECRET `
  -OauthStateSecret YOUR_OAUTH_STATE_SECRET `
  -TokenEncryptionKey YOUR_TOKEN_ENCRYPTION_KEY

Prefiere referencias de Secret Manager para los secretos de producción en lugar de valores de entorno en texto plano al configurar el servicio.

Después del despliegue:

1. Añade la URI de devolución de llamada de Cloud Run al cliente OAuth de V2.

2. Confirma que Firestore se creó en modo nativo.

3. Añade https://<v2-host>/mcp en Claude.

Consideraciones de seguridad

• Los tokens de actualización se cifran con AES-256-GCM antes de escribirse en Firestore.

• Las herramientas MCP nunca devuelven tokens de acceso, tokens de actualización ni códigos de autorización.

• Los registros redactan tokens, secretos, cookies y códigos de autorización.

• Los ID de propiedad de Claude se verifican contra la lista en tiempo real de la API de administración de ese operador.

• Las herramientas fallan en modo cerrado si no hay ningún contexto de operador vinculado a la solicitud.

• Cookies solo HTTPS en producción.

Git

• Este repositorio es solo de V2. El remoto de V1 es git@github.com:devopsbrandmirchi/Ga4McpServer.git y nunca debe añadirse aquí. Crea un repositorio nuevo de GitHub cuando estés listo para publicar V2.