mcp-ga4

Servidor MCP para Google Analytics 4: ejecuta informes, datos en tiempo real, dimensiones personalizadas y gestión de propiedades mediante Claude.

Características

• 9 herramientas que cubren informes, datos en tiempo real, dimensiones/métricas personalizadas, flujos de datos y comentarios

• Dos modos de configuración: propiedad única (variables de entorno) y multi-cliente (config.json)

• Compatible con credenciales de cuenta de servicio y OAuth

• Soporte de fechas relativas (today, yesterday, 7daysAgo, 30daysAgo, 90daysAgo)

• Construido sobre los SDK oficiales de Google con patrones de resiliencia

Related MCP server: Google Analytics 4 MCP Server

Instalación

npm install mcp-ga4

O clona el repositorio:

git clone https://github.com/mharnett/mcp-ga4.git
cd mcp-ga4
npm install
npm run build

Autenticación

mcp-ga4 admite dos familias de credenciales. La selección es determinista y ocurre una vez, al inicio: una clave / cuenta de servicio explícita gana, luego OAuth de usuario, y si ninguna está configurada, el servidor sale con un error de incorporación claro que nombra ambas opciones. No hay una ruta de credenciales local de la máquina integrada en el código y no hay conmutación silenciosa en tiempo de ejecución: las únicas entradas de credenciales son las variables de entorno y (opcionalmente) tu propio config.json por usuario. (Un 403 posterior aparece, por tanto, como error de la API, no como un cambio silencioso a la otra familia de credenciales).

Precedencia: cuando ambas familias están configuradas, la clave / cuenta de servicio tiene prioridad sobre OAuth de usuario.

Opción A: Cuenta de servicio (recomendada para uso desatendido / servidor)

Úsala para cualquier despliegue siempre activo o de servidor. Apunta GOOGLE_APPLICATION_CREDENTIALS (o credentials_file en config.json) a un archivo de clave JSON. La cuenta de servicio debe tener acceso a la propiedad GA4 (Admin → Administración de acceso a la propiedad → añade el correo de la cuenta de servicio con al menos Visor). No se necesita token de actualización: el servidor entrega el archivo de clave directamente a los SDK de GA4:

GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

El archivo de clave puede ser una clave real de cuenta de servicio o un volcado de token OAuth authorized_user; ambos se aceptan mediante la opción keyFile.

Opción B: OAuth de usuario (uso personal / interactivo)

Úsala si quieres que el servidor actúe como un usuario de Google (tu propio inicio de sesión de GA4). Tú aportas tu propio cliente OAuth de Google y generas un token de actualización una vez.

1. En Google Cloud Console, crea un ID de cliente OAuth 2.0 de tipo Aplicación de escritorio. Habilita la API de datos de Google Analytics (y la API de administración si usas las herramientas de dimensiones personalizadas).

2. Exporta tus credenciales de cliente y ejecuta el asistente de token (usa PKCE, abre un navegador e imprime el token en stdout):

   export GA4_CLIENT_ID=...            # from the Desktop-app client
   export GA4_CLIENT_SECRET=...
   node get-refresh-token.cjs          # or: npm run auth

   No redirijas la salida estándar de este comando a un registro compartido: el token de actualización se imprime ahí por diseño.

3. Copia el GA4_REFRESH_TOKEN=... impreso en tu entorno. En tiempo de ejecución, el servidor lee estas tres variables de entorno:

   GA4_CLIENT_ID=...
   GA4_CLIENT_SECRET=...
   GA4_REFRESH_TOKEN=...

El ámbito solicitado se lee de oauth.scope en config.json (ver más abajo), de modo que el asistente y el servidor en ejecución nunca discrepan sobre lo que has concedido.

Ámbitos (concesión mínima)

Los ámbitos viven en config.json bajo oauth.scope. El valor predeterminado incluido es:

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

analytics.edit es necesario porque ga4_create_custom_dimension modifica la propiedad mediante la API de administración. Si solo necesitas acceso de lectura, sobrescribe oauth.scope en tu propio config.json con solo analytics.readonly y vuelve a ejecutar el asistente.

Configuración

Seguridad: nunca compartas tu archivo .mcp.json ni lo confirmes en git: puede contener credenciales de API. Añade .mcp.json a tu .gitignore.

Modo 1: Propiedad única (variables de entorno)

Establece un ID de propiedad más una de las familias de autenticación anteriores:

GA4_PROPERTY_ID=123456789
# then EITHER the OAuth trio (GA4_CLIENT_ID/SECRET/REFRESH_TOKEN)
# OR a service account: GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

Modo 2: Multi-cliente (config.json)

Crea un config.json en la raíz del proyecto para asignar varias propiedades GA4 a directorios de proyecto. El servidor detecta automáticamente qué propiedad usar según el directorio de trabajo del llamador. Las credenciales provienen del entorno (opción A/B anterior); config.json puede incluir opcionalmente una ruta credentials_file de cuenta de servicio para una configuración solo con SA.

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/analytics.readonly https://www.googleapis.com/auth/analytics.edit"
  },
  "clients": {
    "client-a": {
      "name": "Client A",
      "folder": "/path/to/client-a/project",
      "property_id": "123456789"
    },
    "client-b": {
      "name": "Client B",
      "folder": "/path/to/client-b/project",
      "property_id": "987654321"
    }
  }
}

Uso

Claude Code (.mcp.json)

Modo de propiedad única:

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["mcp-ga4"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

Modo multi-cliente:

{
  "mcpServers": {
    "ga4": {
      "command": "node",
      "args": ["/path/to/mcp-ga4/dist/index.js"]
    }
  }
}

Claude Desktop: añádelo a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows).

Patrones de consulta comunes

Páginas principales: dimensions=pagePath, metrics=screenPageViews, order_by=screenPageViews

Fuentes de tráfico: dimensions=sessionSource,sessionMedium, metrics=sessions,totalUsers

Tendencia diaria: dimensions=date, metrics=sessions,totalUsers

Rendimiento de campañas: dimensions=sessionCampaignName, metrics=sessions,conversions

Desglose por dispositivo: dimensions=deviceCategory, metrics=sessions,totalUsers

Herramientas

Formatos de fecha

Usa YYYY-MM-DD para fechas absolutas, o estos atajos relativos:

• today

• yesterday

• 7daysAgo

• 30daysAgo

• 90daysAgo

Dimensiones y métricas comunes

Dimensiones: date, dateHour, eventName, pagePath, pageTitle, sessionSource, sessionMedium, sessionCampaignName, country, city, deviceCategory, browser, operatingSystem, landingPage, pageReferrer, newVsReturning, firstUserSource, firstUserMedium, firstUserCampaignName

Métricas: sessions, totalUsers, newUsers, activeUsers, screenPageViews, eventCount, conversions, engagedSessions, engagementRate, averageSessionDuration, bounceRate, sessionsPerUser, screenPageViewsPerSession, userEngagementDuration

Actualización de datos

• Informes estándar: retraso de 24-48 horas

• Informes en tiempo real: solo los últimos 30 minutos

Arquitectura

Construido sobre:

• @google-analytics/data -- API de datos de GA4 para informes

• @google-analytics/admin -- API de administración de GA4 para gestión de propiedades

• cockatiel -- resiliencia (reintentos, interruptor de circuito)

• pino -- registro estructurado

Licencia

MIT

Autor

Creado por Mark Harnett / drak-marketing