ga4-mcp-worker

Un servidor MCP de Google Analytics 4 de solo lectura que se ejecuta en Cloudflare Workers para que tus compañeros puedan consultar GA4 desde Claude sin tener nada instalado localmente: no Python, no gcloud, no archivo ADC y, con esta versión, tampoco una contraseña compartida. Sumar el servidor significa hacer clic en «Conectar», iniciar sesión con tu propia cuenta de Google y responder preguntas sobre GA4 siendo tú mismo.

Replica la superficie de herramientas del servidor googleanalytics/google-analytics-mcp oficial, pero llama a las API REST de Google Analytics directamente, ya que las librerías cliente oficiales no funcionan en el runtime de Workers.

Lee esto primero: docs/IMPLEMENTATION-NOTES.md § Qué se ha probado y qué no. La verificación manual de extremo a extremo está hecha, pero algunas superficies (los endpoints v1alpha, la paginación) siguen solo respaldadas por fixtures.

Autenticación: OAuth por usuario

Cada integrante del equipo entra con su propia cuenta de Google. No hay ningún secreto compartido ni una única credencial de Google de la que todos dependan; consulta [PRODUCTION.md § I](PRODUCTION.md#el-modelo-de-en – the full identity model) y docs/PRODUCTION-PART2.md § VIII para el diseño completo y en qué se diferencia del antiguo modo contras un secreto compartido. El acceso se limita a las cuentas de Google de @zuddl.com (ALLOWED_EMAIL_DOMAIN en wrangler.toml).

GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET siguen siendo obligatorios: Google exige que toda aplicación que pida datos de usuario esté registrada, y esos dos valores son la clave usada en el despliegue una única vez. Lo que desaparece es el refresh token que se generaba a mano y la contraseña que los compañeros solían escribir.

Documentación de la documentación

Related MCP server: GA4 MCP Server

Propiedades de GA4 para uso interno

El servidor es independiente de la propiedad: toda herramienta acepta el parámetro property_id, tanto con 314138239 como con "properties/314138239". Si se omite, se usará el DEFAULT_PROPERTY_ID de wrangler.toml, por defecto la propiedad destino, para que no tengas que memorizar un número. Llama a get_account_summaries para listar todo lo que las credenciales pueden ver.

Herramientas (9)

run_report acepta el conjunto completo oficial de parámetros: property_id, date_ranges (una lista, para que la comparación entre periodos funcione en una sola petición), dimensions, dimension_filter, metric_filter, order_bys, limit, offset, currency_code y return_property_quota. run_realtime_report usa la misma estructura, pero sin date_ranges y currency_code.

Las descripciones de las herramientas son adrede más extensas porque ofrecen ejemplos funcionantes para cada tipo de filtro y son el único sitio de donde el modelo aprende el formato de la petición. Trata cualquier edición de las mismas como un cambio de comportamiento.

Endpoints

Todo lo demás devuelve 404.

En modo OAuth, /health significa menos. No hay una credencial compartida que se pueda comprobar, así que un 200 solo confirma que hay registro de aplicación y que OAUTH_KV (la tienda de concesiones) es accesible; no que la sesión de una persona sigan siendo válida. Una sesión de usuario puede caducar o revocarse incluso mientras /health está verde. Eso es propio de la autenticación por usuario, no un fallo.

El Worker registra una línea de JSON por petición MCP, por cada rechazo de autenticación, por cada error de herramienta, por cada fallo de health, y eventos propios de OAuth (oauth_authorize_redirect, oauth_authorized, oauth_domain_rejected, etc.). No se registra ningún material del token. Todas las llamadas a Google llevan el User-Agent propio ga4-mcp-worker/1.0.0 (+cloudflare-workers) para así poder atribuir gasto de cuota.

Aplicación de modo solo lectu

Tres capas independientes, todas presentes:

1. Alcance OAuth. Todo token (el viejo token de modo o el de una integrante) se solicita con https://www.googleapis.com/auth/analytics.readonly y nada más (solo openid/email para verificar la identidad en el modo OAuth — ver src/google-oauth.ts: no dan acceso a datos). Google rechaza cualquier intento de escritura desde del servidor. Esta es la garantía real. El documento SETUP-GUIDE.md sirve para comprobar eso mismo con tokeninfo.

2. Endpoints permitidos. Las expresiones regulares se revisan dentro de los dos helpers de fetch, antes de llamar por red. Si en una edición futura se introduce un endpoint de escritura, se lanza una excepción en vez de salir a la red.

3. Cero verbos mutantes. No hay ningún PATCH, PUT ni DELETE en el repositorio. Solo hay tres usos de fetch mediante el código: la fábrica del token (POST), gaGet (GET) y gaPost (POST).

Los puntos :runReport, :runRealtimeReport y :runFunnelReport usan HTTP POST pero se trata de peticiones de consulta: — el cuerpo contiene la definición del informe porque es demasiado para una cadena de query. En GA4 no se crea ni se modifica nada.

Comandos rápidos

npm install

npm run typecheck && npm run dry-run

npm run deploy

npm run tail

curl -s https://ga4-mcp-worker.YOUR-SUBDOMAIN.workers.dev/health

Define los dos secretos que necesitan ambos modos de autenticación (escíbelos interactivamente, ya que redireccionarlos con tubería descuida los valores):

npx wrangler secret put GOOGLE_CLIENT_ID

npx wrangler secret put GOOGLE_CLIENT_SECRET

Conecta desde Claude Code — no hace falta un servicio de headers, pues la autorización ocurre por el navegador:

claude mcp add --transport http --scope user ga4 https://ga4-mcp-worker.YOUR-SUBDOMAIN.workers.dev/mcp

Luego, en una sesión interactiva de claude, ejecuta /mcp, elige ga4 y auténtica con tu cuenta Google.

Más

• Escollos, cobertura de pruebas y costes de ejecución: docs/IMPLEMENTATION-NOTES.md

• Tutorial del primer despliegue: SETUP-GUIDE.md → parte 2

• Endurecimiento, monitorización y la guía de operaciones de OAuth: PRODUCTION.md → parte 2