Saltar al contenido
Raúl Veneri
Contacto

Google Analytics en Claude Code

Guía paso a paso para conectar el servidor MCP oficial de Google Analytics a Claude Code en Windows. Una vez listo, le preguntas a Claude por datos de tus propiedades GA4 en lenguaje natural: sesiones, usuarios, informes a medida y datos en tiempo real.

github.com/googleanalytics/google-analytics-mcp

Qué vas a montar

El servidor MCP de Google Analytics se ejecuta en local y hace de puente entre Claude Code y las APIs de GA4. Piezas necesarias:

  • Python 3.10+ — ejecuta el servidor MCP.
  • pipx — lanza el paquete analytics-mcp en un entorno aislado.
  • Google Cloud SDK (gcloud) — autenticación (ADC) contra las APIs de GA.
  • Proyecto de Google Cloud — contenedor de las APIs habilitadas y del cliente OAuth.
  • APIs habilitadas — Google Analytics Admin API + Google Analytics Data API.
  • Cliente OAuth (tipo Desktop) — credencial para el login de ADC.
El proyecto de Google Cloud es solo un contenedor administrativo. Las APIs de GA Data/Admin son de solo lectura y sin coste para este uso.

Requisitos previos

Comprueba qué tienes ya instalado:

python --version    # necesitas 3.10+
pip --version
claude --version

1. Instalar pipx

python -m pip install --user pipx
python -m pipx ensurepath

Cierra y reabre la terminal después (actualiza el PATH).

2. Instalar Google Cloud SDK

Descarga el instalador oficial para Windows desde cloud.google.com/sdk. Instálalo a nivel de usuario (no requiere admin; las credenciales son por-usuario de todas formas) y reabre la terminal al terminar.

gcloud --version

3. Proyecto y APIs

Crea o selecciona un proyecto en la consola de Google Cloud y anota su PROJECT_ID (ojo: el ID no es el nombre; suele ser algo como mi-proyecto-1234567890). Desde terminal:

gcloud projects list
gcloud config set project TU_PROJECT_ID

Habilita las dos APIs necesarias (Consola → APIs y servicios → Biblioteca, busca y pulsa Habilitar):

  • Google Analytics Admin API
  • Google Analytics Data API

4. Pantalla de consentimiento OAuth

Antes de crear el cliente OAuth, Google pide configurar la pantalla de consentimiento (Consola → APIs y servicios → Pantalla de consentimiento de OAuth):

  • App name: cualquier nombre, ej. Analytics MCP.
  • User support email: tu correo de Google.
  • Audience / User type: External (obligatorio con Gmail personal; Internal solo existe con Google Workspace).
  • Developer contact email: tu correo de Google.
  • Scopes: déjalo vacío, no añadas nada.

La app queda en modo Testing. Imprescindible: añádete como test user, si no el login fallará con Error 403: access_denied. Sección Test users → Add users → tu correo de Google. No publiques la app (no necesita verificación de Google para uso personal).

5. Crear el cliente OAuth (Desktop)

Consola → APIs y servicios → Credenciales → Crear credenciales → ID de cliente de OAuth:

  • Tipo de aplicación: Aplicación de escritorio (Desktop app).
  • Nombre: cualquiera, ej. analytics-mcp-desktop.
  • Descarga el JSON.

Guárdalo fuera de cualquier repositorio Git (es un secreto, no debe commitearse). Carpeta sugerida:

mkdir $env:APPDATA\gcloud\oauth -Force
move $env:USERPROFILE\Downloads\client_secret_*.json $env:APPDATA\gcloud\oauth\analytics-mcp.json

Ruta final de ejemplo: C:\Users\TU_USUARIO\AppData\Roaming\gcloud\oauth\analytics-mcp.json

6. Login ADC con el scope de Analytics

Esto genera las credenciales que usará el servidor MCP. Ejecuta todo en una sola línea y entrecomilla los scopes (PowerShell interpreta la coma como separador de array si no van entre comillas):

gcloud auth application-default login --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform" --client-id-file="C:\Users\TU_USUARIO\AppData\Roaming\gcloud\oauth\analytics-mcp.json"

Se abre el navegador. Inicia sesión con la cuenta que añadiste como test user (y que tiene acceso a la propiedad GA4) y acepta los permisos. La consola imprime la ruta de las credenciales, normalmente C:\Users\TU_USUARIO\AppData\Roaming\gcloud\application_default_credentials.json.

El cliente OAuth (analytics-mcp.json) no es lo mismo que las credenciales ADC finales (application_default_credentials.json). El primero se consume para generar el segundo, que es el que apunta el MCP.

Errores comunes en este paso

  • running scripts is disabled — execution policy de PowerShell. Solución: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned (permite scripts locales y remotos firmados, solo para tu usuario).
  • Missing expression after unary operator '--' — el comando quedó partido en varias líneas. Pégalo todo en una sola línea.
  • cloud-platform scope is required but not requested — la coma de --scopes se interpretó como array. Entrecomilla el valor completo.
  • Error 403: access_denied — tu correo no está como test user. Añádelo en la pantalla de consentimiento.

7. Añadir el servidor a Claude Code

Verifica primero que pipx puede lanzar el paquete (la primera vez descarga y crea el venv, tarda un poco):

python -m pipx run analytics-mcp --help

Debe acabar mostrando Starting MCP Stdio Server: Google Analytics MCP Server. Añade el servidor con scope user (disponible en todos tus proyectos; quítalo para solo el proyecto actual):

claude mcp add analytics-mcp --scope user --env GOOGLE_APPLICATION_CREDENTIALS="C:\Users\TU_USUARIO\AppData\Roaming\gcloud\application_default_credentials.json" --env GOOGLE_PROJECT_ID="TU_PROJECT_ID" -- python -m pipx run analytics-mcp
Se usa python -m pipx run en lugar de pipx run a secas para no depender de que pipx esté en el PATH cuando Claude Code arranca el servidor.

8. Verificar

  • Reinicia Claude Code (los servidores MCP se cargan al arrancar).
  • Ejecuta /mcp — debe aparecer analytics-mcp como connected.
  • Prueba en lenguaje natural: "lista mis propiedades GA4", "sesiones de los últimos 7 días", "usuarios activos ahora mismo".

La primera llamada real puede tardar (levanta el venv); las siguientes son rápidas.

Herramientas que expone el servidor

  • Listar cuentas y propiedades (Admin API).
  • Ejecutar informes a medida con métricas y dimensiones (Data API, runReport).
  • Consultar la metadata de dimensiones y métricas disponibles.
  • Datos en tiempo real (realtime).

Seguridad

  • No commitees ni el cliente OAuth ni las credenciales ADC. Ambos viven fuera del repo.
  • El scope usado es analytics.readonly: solo lectura, no puede modificar tu configuración de GA.
  • Para revocar el acceso: borra application_default_credentials.json o revoca la app en myaccount.google.com/permissions.