Skip to main content
Glama
mcp-google-analytics

mcp-google-analytics

README.md
# mcp-google-analytics

Servidor MCP para Google Analytics 4: gestión de propiedades, reportes y onboarding completo de sitios nuevos (crear propiedad → stream web → sitio con gtag → métricas → verificación).

## Instalación

```bash
npm install
npm run build
```

## Autenticación con Google

### 1. Proyecto de Google Cloud

1. En [Google Cloud Console](https://console.cloud.google.com/) crea o elige un proyecto.
2. Habilita **Google Analytics Admin API** y **Google Analytics Data API**.
3. En *Google Auth Platform → Branding/Audience*, configura la pantalla de consentimiento. Si queda en modo *Testing*, añade tu cuenta como usuario de prueba.

### 2a. OAuth de usuario (recomendado)

1. *Google Auth Platform → Clients → Create client → Desktop app*. Descarga el JSON.
2. Apunta `GOOGLE_OAUTH_CLIENT_FILE` a ese archivo.
3. Autoriza una vez con `npm run auth` o con la herramienta `ga_auth_login`. Se abre el consentimiento de Google y el refresh token se guarda en `~/.config/mcp-google-analytics/token.json` (permisos 600).

Scopes solicitados: `analytics.edit` (crear/actualizar/borrar propiedades y streams, eventos clave) y `analytics.readonly` (reportes).

### 2b. Cuenta de servicio (servidores / CI)

1. Crea una cuenta de servicio y descarga su clave JSON.
2. En GA4, *Administrar → Gestión de acceso a la cuenta*, añade el email de la cuenta de servicio con rol **Editor**.
3. Define `GOOGLE_APPLICATION_CREDENTIALS` con la ruta de la clave.

Si ambas opciones están configuradas, gana OAuth.

## Configuración en Cursor / Claude Desktop

```json
{
  "mcpServers": {
    "google-analytics": {
      "command": "node",
      "args": ["/mnt/proyectos/mcp-google-analytics/dist/index.js"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_FILE": "/ruta/client_secret.json",
        "GA_MCP_DEFAULT_ACCOUNT_ID": "123456789",
        "GA_MCP_SITES_DIR": "/mnt/proyectos/sitios"
      }
    }
  }
}
```

Variables disponibles: ver `.env.example`.

## Herramientas

| Herramienta | Qué hace |
| --- | --- |
| `ga_auth_status` | Muestra el modo de credenciales y si hay acceso autorizado |
| `ga_auth_login` | Inicia el flujo OAuth (loopback + PKCE) y devuelve la URL de consentimiento |
| `ga_list_accounts` | Cuentas y propiedades accesibles |
| `ga_list_properties` | Propiedades GA4 de una cuenta (`showDeleted` incluye papelera) |
| `ga_get_property` | Detalle de una propiedad (incluye `deleteTime`/`expireTime` si está en papelera) |
| `ga_create_property` | Crea una propiedad y, opcionalmente, su stream web |
| `ga_update_property` | Actualiza nombre, zona horaria, moneda o industria |
| `ga_delete_property` | Soft-delete (papelera) de una propiedad; recuperable en la UI hasta `expireTime` |
| `ga_list_data_streams` | Streams de una propiedad con sus measurement IDs |
| `ga_create_web_stream` | Crea un stream web y devuelve el snippet gtag |
| `ga_delete_data_stream` | Elimina un data stream de una propiedad |
| `ga_get_tracking_snippet` | Snippet gtag para un measurement ID |
| `ga_configure_metrics` | Eventos clave, dimensiones y métricas personalizadas |
| `ga_basic_report` | Usuarios, sesiones, fuentes de tráfico, páginas top y tendencia diaria |
| `ga_run_report` | Reporte libre con cualquier dimensión y métrica de la Data API |
| `ga_realtime_report` | Actividad de los últimos 30 minutos |
| `ga_dashboard_snapshot` | KPIs del periodo y tiempo real en una sola llamada |
| `site_generate` | Genera un sitio estático con gtag en todas las páginas |
| `site_inject_tracking` | Inserta o actualiza gtag en HTML existente (idempotente) |
| `site_verify_tracking` | Comprueba el tag en la URL pública y la llegada de eventos en tiempo real |
| `site_onboard` | Flujo completo de principio a fin; se puede reanudar |
| `site_onboarding_status` | Estado guardado de cada sitio |

## Flujo `site_onboard`

1. Crea la propiedad GA4, o reutiliza `propertyId`.
2. Crea el stream web para `siteUrl`, o reutiliza uno existente con la misma URL, y obtiene el `G-XXXX`.
3. Genera el sitio en `GA_MCP_SITES_DIR/<slug>` o, si pasas `existingSiteDir`, inyecta gtag en ese sitio.
4. Configura `keyEvents`, `customDimensions` y `customMetrics` si los pasas.
5. Verifica: revisa el tag en `siteUrl` y consulta el reporte en tiempo real. Con `sendTestEvent=true` envía un evento por Measurement Protocol.

El estado se guarda en `~/.config/mcp-google-analytics/sites.json`. Volver a llamar con el mismo `siteName` continúa donde quedó, sin duplicar la propiedad.

El servidor no publica el sitio. Despliega la carpeta generada en tu hosting y luego ejecuta `site_verify_tracking`.

## Dashboards: limitaciones

GA4 no tiene API para crear o editar dashboards ni reportes de su interfaz. Por eso:

- `ga_dashboard_snapshot` entrega los datos de un dashboard para que el agente los presente.