Google Analytics + AdSense Remote MCP

Servidor MCP remoto de solo lectura para GA4 y AdSense Management API v2, que se ejecuta en Cloudflare Workers. El enrutamiento HTTP usa Hono, el transporte MCP usa createMcpHandler() y la autorización OAuth del cliente usa Cloudflare Access Managed OAuth.

Un solo Worker está fijado a un único par de refresh tokens de Google OAuth y maneja todas las propiedades de GA4 y cuentas de AdSense que esa cuenta de Google puede leer. No es posible sustituir las credenciales OAuth, los hosts de la API de Google ni las operaciones de escritura desde las llamadas a las herramientas.

Implementación con un clic en Cloudflare

El botón duplica este repositorio público de GitHub en la cuenta del propio usuario, y compila e implementa el Worker tras solicitar el nombre del Worker y la siguiente configuración.

• Configuración no secreta: CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD

• Secretos: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN

Antes de pulsar el botón, emita GOOGLE_REFRESH_TOKEN siguiendo el procedimiento que se describe más abajo, autorizando únicamente los scopes de solo lectura. La habilitación de la aplicación Cloudflare Access y de Managed OAuth la realiza el propio usuario después de la implementación.

Related MCP server: Google Analytics MCP server on Cloudflare Workers

Endpoints

Herramientas MCP

• ga4_run_report, ga4_run_realtime_report, ga4_run_pivot_report, ga4_run_funnel_report

• ga4_get_metadata, ga4_check_compatibility

• ga4_admin_read: operaciones GET/list bajo accountSummaries, accounts, properties de la GA4 Admin API v1alpha.

• adsense_generate_report

• adsense_read: operaciones GET/list bajo accounts de la AdSense Management API v2.

Todas las herramientas están anotadas como de solo lectura en MCP y sus entradas se validan con Zod. No se aceptan URLs externos, cabeceras HTTP arbitrarias ni la ejecución arbitraria de POST/PUT/PATCH/DELETE. Los errores sin procesar de Google no se incluyen en la respuesta MCP, pero se registran completos en los Worker Logs de la cuenta de Cloudflare de destino para facilitar la investigación de incidencias.

Preparación de OAuth de Google

1. En el proyecto de Google Cloud, habilite Google Analytics Data API, Google Analytics Admin API y AdSense Management API.

2. Configure la pantalla de consentimiento de OAuth y solicite únicamente https://www.googleapis.com/auth/analytics.readonly para GA4 y https://www.googleapis.com/auth/adsense.readonly para AdSense.

3. En Credentials, cree un OAuth Client ID y seleccione Desktop app como tipo de aplicación. AdSense no admite cuentas de servicio; se requiere el flujo de aplicación instalada.

4. Como el refresh token puede no volver a mostrarse, guárdelo en un gestor de contraseñas seguro en el momento de su emisión. No lo coloque en el repositorio, en Issues, en registros de CI ni en wrangler.jsonc.

Google revoca los access tokens en poco tiempo. El Worker vuelve a obtener el access token mediante la concesión de refresh token en cada ejecución de una herramienta MCP, por lo que no es necesario que el Worker almacene tokens de forma persistente.

Emisión de un refresh token con Python

Funciona únicamente con Python 3.10 o posterior y no requiere paquetes adicionales. scripts/get_google_refresh_token.py utiliza PKCE, escucha un callback local y no guarda credenciales, access tokens ni refresh tokens en archivos.

Configuración del URI de redirección en Google Cloud Console

Este Worker no recibe el callback directamente de Google. El cliente OAuth que cree en Credentials debe ser siempre una Desktop app. En las aplicaciones de escritorio no es necesario configurar Authorized redirect URIs ni Authorized JavaScript origins en Cloud Console.

El script de Python elige un puerto local libre en tiempo de ejecución y envía a Google un URI de redirección de loopback, por ejemplo:

http://127.0.0.1:54321/callback/

Este es el callback de loopback que Google permite para aplicaciones de escritorio. No registre https://<worker-host>/callback, https://<worker-host>/mcp ni las URLs de Cloudflare Access como URI de redirección del cliente OAuth de Google. Evite también usar este script con un cliente OAuth de tipo aplicación web.

python scripts/get_google_refresh_token.py

Se le pedirán GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET. En el navegador, inicie sesión con la cuenta de Google que usará el Worker y autorice únicamente los siguientes scopes de solo lectura.

Si desea cancelar la autorización del navegador, pulse Ctrl+C en el terminal que está a la espera. Se cerrará el listener de callback local y se terminará sin guardar tokens.

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

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

Copie la única línea que se muestra al finalizar correctamente e introdúzcala en el campo Secret GOOGLE_REFRESH_TOKEN del Deploy Button, o en el siguiente comando interactivo:

pnpm wrangler secret put GOOGLE_REFRESH_TOKEN

Si el Client ID / secret tampoco están configurados, configúrelos de la misma manera.

pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET

Si la pantalla de consentimiento de OAuth de Google sigue en External + Testing, el refresh token normalmente caduca en 7 días. Antes de su uso continuado, migre a Production y complete la verificación que Google solicita. Si se produce invalid_grant, revoque el acceso de esta aplicación en la cuenta de Google, vuelva a ejecutar el script y actualice el Secret del Worker.

Desarrollo local

Requisitos: Node.js 20 o superior, Corepack y una cuenta de Cloudflare que pueda usar Cloudflare Zero Trust.

corepack enable
pnpm install
Copy-Item .dev.vars.example .dev.vars
pnpm check
pnpm dev --local

Configure las credenciales reales de Google en .dev.vars. Este archivo no se añade a Git.

Implementación en Cloudflare

1. Cambie name, CF_ACCESS_TEAM_DOMAIN y CF_ACCESS_AUD en wrangler.jsonc por los valores de su configuración de Cloudflare Access.

2. Configure los Secretos individualmente.

pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET
pnpm wrangler secret put GOOGLE_REFRESH_TOKEN
pnpm run deploy

3. En el panel de Cloudflare Zero Trust, cree una aplicación de servidor MCP dirigida a https://<host>/mcp del Worker.

4. Cree una Access Policy para las direcciones de correo o grupos de ID permitidos y deniegue a los usuarios no autorizados.

5. En Advanced settings, habilite Managed OAuth. Verifique que la etiqueta de audiencia de la aplicación y el dominio del equipo coinciden con los valores de configuración del Worker.

Cloudflare Access se encarga del descubrimiento de OAuth, el registro dinámico de clientes, el flujo de código de autorización, PKCE y la renovación de access tokens. No añada /authorize, /token ni /register propios dentro del Worker.

Conexión de clientes MCP

El endpoint MCP es https://<host>/mcp. En la primera conexión se abre el inicio de sesión y la autorización de Cloudflare Access.

• Inspector: inicie npx @modelcontextprotocol/inspector@latest, conéctese al endpoint y escanee / liste todas las herramientas.

• Codex, etc.: registre el endpoint en la configuración MCP remota compatible con OAuth.

• ChatGPT: registre el endpoint en la app / conector MCP personalizado del modo Developer, complete la autorización OAuth y ejecute el escaneo de herramientas. La disponibilidad de ChatGPT depende del plan contratado, la configuración del Workspace y la región.

Verificación

pnpm check

check ejecuta en orden ESLint, TypeScript, Vitest, la sincronización de tipos de los bindings del Worker y wrangler deploy --dry-run. No se realizan pruebas automáticas de consultas a cuentas reales de Google. Tras la implementación, ejecute un informe de GA4 y un informe de AdSense a través de Access con el Inspector y con el cliente MCP que vaya a utilizar.

Diagnóstico de incidencias de la API de Google

Cuando falla la API de Google, el Worker emite un evento de diagnóstico JSON en los Cloudflare Workers Logs. Se escribe sin omitir el cuerpo de la respuesta HTTP de Google, la URL y el cuerpo de la solicitud, y el nombre, mensaje y traza de la excepción. Esta es una configuración de depuración que solo pueden ver los lectores de registros de la cuenta de Cloudflare donde se ha implementado. Si va a transferir, compartir o publicar los registros externamente, desactive previamente este registro detallado. No se seguirá incluyendo en la respuesta MCP.

pnpm wrangler tail --format json

Ejemplo: {"event":"google_request_failed","tool":"ga4_run_report","category":"google_api","upstreamStatus":403,"error":{"request":{"url":"..."},"responseBody":"...","stack":"..."}}. oauth_refresh indica un fallo al renovar el refresh token, google_api indica un rechazo de la API de GA4 / AdSense, y unexpected indica un fallo inesperado como de red.

Licencia

Licencia MIT