ga-gsc-analytics

Servidor MCP de solo lectura que expone datos de Google Analytics 4 y Google Search Console (ámbitos analytics.readonly + webmasters.readonly) a Claude Code / Codex.

¿Nuevo aquí? Sigue ONBOARDING.md para un recorrido de cero a funcionando (instalar Claude Code, obtener credenciales, autorizar, verificar). El resto de este archivo es material de referencia.

Agentes de IA: este archivo también sirve como AGENTS.md — comienza aquí para la configuración, luego lee skills/analyze-ga-gsc/SKILL.md para saber cómo usar las herramientas (comprobaciones de acceso, rangos de fechas predeterminados, semántica de GA4 vs. GSC, formato de entrega de presentación). Nunca pidas a un usuario que pegue credenciales en el chat.

Herramientas

• analytics_auth_start / analytics_auth_status — flujo OAuth local + comprobación de estado

• analytics_list_sources — lista las propiedades de GA4 y los sitios de GSC disponibles para la cuenta autorizada

• ga_run_report — ejecuta un informe de GA4

• gsc_query_search_analytics — consulta datos de Search Console

• analytics_presentation_snapshot — instantánea combinada de GA4 + GSC para informes

Related MCP server: BigQuery MCP Server

Configuración (por usuario)

Cada usuario se autoriza con su propia cuenta de Google y mantiene su propio token local — nunca compartas secretos de client_secret.json ni tokens.json entre máquinas.

1. Cliente OAuth de Google Cloud: crea (o reutiliza un existente) un cliente de escritorio OAuth 2.0 en Google Cloud Console y descarga su client_secret.json. Si la pantalla de consentimiento está en estado de publicación "Pruebas", añade primero la cuenta de Google de cada nuevo usuario como usuario de prueba, o la autorización fallará con acceso denegado.

2. Coloca las credenciales en ~/.config/ga-gsc-analytics/client_secret.json (o apunta GA_GSC_CLIENT_SECRET a una ruta personalizada).

3. Concede acceso a los datos: la cuenta de Google que autoriza necesita permisos reales en la propiedad de GA4 objetivo (Analytics Admin → Administración de acceso a la propiedad) y en el sitio de GSC (Search Console → Configuración → Usuarios y permisos).

4. Compila el servidor (solo necesario si cambias mcp/server.mjs; el repositorio incluye un mcp/server.bundle.cjs precompilado):

pnpm install
pnpm run build   # bundles mcp/server.mjs -> mcp/server.bundle.cjs

5. Registra el servidor MCP. Ya sea:

   • Claude Code, a nivel de usuario: claude mcp add ga-gsc-analytics -- node /path/to/ga-gsc-analytics/mcp/server.bundle.cjs

   • Claude Code / Codex, con ámbito de proyecto: este repositorio ya incluye un .mcp.json relativo ({"mcpServers": {"ga_gsc_analytics": {"command": "node", "args": ["./mcp/server.bundle.cjs"]}}}) — cópialo en un proyecto, o enlaza simbólicamente / incluye esta carpeta completa, y se detectará automáticamente cuando se abra ese proyecto.

6. Autoriza: llama a la herramienta analytics_auth_start desde tu herramienta de IA — abre un flujo OAuth local en el navegador y escribe ~/.config/ga-gsc-analytics/tokens.json.

7. Verifica: llama a analytics_auth_status (debería informar authorized: true), luego analytics_list_sources para confirmar que aparecen las propiedades de GA4 / sitios de GSC esperados.

Anulaciones de configuración

Desarrollo

pnpm run check   # syntax check
pnpm test        # node --test tests/*.test.mjs