@weppa-cloud/mcp-google-analytics

MCP server para Google Analytics 4 con herramientas orientadas a growth y marketing.

🚀 Versión 1.3.1 - Validación Completa de Dimensiones

Ahora con validación inteligente de dimensiones GA4:

• ✅ Auto-transformación de dimensiones legacy a GA4
• 🔍 Sugerencias inteligentes para dimensiones inválidas
• 🎯 Validación de compatibilidad entre dimensiones
• 📊 Soporte completo para dimensiones custom

Ahora puedes modificar configuraciones en GA4, no solo leer datos:

• ✅ Marcar eventos como conversiones
• ❌ Remover marcas de conversión
• 🎯 Crear eventos personalizados
• 📋 Gestionar propiedades y data streams

Instalación

npx @weppa-cloud/mcp-google-analytics@latest

Configuración

1. Credenciales con permisos de escritura

Tu Service Account ahora necesita el rol de Editor en GA4:

1. Ve a Google Analytics → Admin → Property Access Management
2. Agrega tu Service Account con rol "Editor"
3. Las credenciales ahora incluyen automáticamente los scopes necesarios

2. Configuración en Claude Desktop

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["@weppa-cloud/mcp-google-analytics@latest"],
      "env": {
        "GA_PROPERTY_ID": "YOUR_PROPERTY_ID",
        "GOOGLE_ANALYTICS_CREDENTIALS": "/path/to/credentials.json"
      }
    }
  }
}

🆕 Herramientas de Administración (v1.3.0)

Gestión de Conversiones

list_conversion_events

Lista todos los eventos marcados como conversiones:

"Lista todos mis eventos de conversión"

mark_event_as_conversion

Marca un evento existente como conversión:

"Marca el evento 'add_to_cart' como conversión"
"Convierte 'newsletter_signup' en una conversión"

remove_conversion_event

Remueve la marca de conversión de un evento:

"Quita la marca de conversión del evento 'page_view'"

Eventos Personalizados

create_custom_event

Crea eventos personalizados basados en condiciones:

"Crea un evento 'high_value_purchase' cuando purchase > 100"
"Crea 'engaged_user' cuando session_duration > 300"

Información de Propiedad

get_property_details

Obtiene detalles de configuración de la propiedad:

"Muéstrame la configuración de mi propiedad GA4"

list_data_streams

Lista todos los data streams configurados:

"Qué data streams tengo configurados?"

Dimensiones GA4 Válidas

⚠️ Cambios Importantes de Universal Analytics a GA4

Si estás migrando de Universal Analytics (GA3), estas son las dimensiones que han cambiado:

| Dimensión Legacy (GA3) | Dimensión GA4 Correcta | |---------------------|---------------------| | landingPagePath | landingPagePlusQueryString | | hostname | hostName | | channelGrouping | sessionDefaultChannelGroup | | source | sessionSource | | medium | sessionMedium | | campaign | sessionCampaignName | | keyword | sessionGoogleAdsKeyword |

📊 Dimensiones GA4 Más Comunes

Páginas y Contenido

• pagePath - Ruta de la página (sin query string)
• pageTitle - Título de la página
• landingPagePlusQueryString - Página de aterrizaje con query string
• pagePathPlusQueryString - Ruta completa con query string
• hostName - Nombre del host

Fuentes de Tráfico

• sessionSource - Fuente de la sesión
• sessionMedium - Medio de la sesión
• sessionCampaignName - Nombre de la campaña
• sessionDefaultChannelGroup - Grupo de canal predeterminado
• sessionSourceMedium - Combinación fuente/medio

Usuario y Demografía

• country - País
• city - Ciudad
• region - Región/Estado
• userAgeBracket - Rango de edad
• userGender - Género
• language - Idioma

Tecnología

• deviceCategory - Categoría del dispositivo (desktop, mobile, tablet)
• browser - Navegador
• operatingSystem - Sistema operativo
• screenResolution - Resolución de pantalla
• platform - Plataforma

Tiempo

• date - Fecha (YYYYMMDD)
• dateHour - Fecha y hora
• dayOfWeek - Día de la semana
• hour - Hora del día

Eventos

• eventName - Nombre del evento
• isConversionEvent - Si es un evento de conversión

💡 Ejemplos de Uso con Dimensiones

// ❌ INCORRECTO (dimensiones GA3)
{
  dimensions: ["landingPagePath", "source", "medium"]
}

// ✅ CORRECTO (dimensiones GA4)
{
  dimensions: ["landingPagePlusQueryString", "sessionSource", "sessionMedium"]
}

Métricas GA4 Válidas

⚠️ Cambios Importantes de Universal Analytics a GA4

Si estás migrando de Universal Analytics (GA3), estas son las métricas que han cambiado:

| Métrica Legacy (GA3) | Métrica GA4 Correcta | |---------------------|---------------------| | users | activeUsers o totalUsers | | pageviews | screenPageViews | | avgSessionDuration | averageSessionDuration | | goalCompletionsAll | conversions | | transactionRevenue | totalRevenue |

📊 Métricas GA4 Más Comunes

Usuarios

• activeUsers - Usuarios activos
• totalUsers - Total de usuarios
• newUsers - Usuarios nuevos
• returningUsers - Usuarios recurrentes

Sesiones y Engagement

• sessions - Total de sesiones
• engagementRate - Tasa de engagement
• bounceRate - Tasa de rebote
• averageSessionDuration - Duración promedio de sesión
• engagedSessions - Sesiones con engagement

Páginas/Pantallas

• screenPageViews - Vistas de página
• screenPageViewsPerSession - Páginas por sesión
• views - Vistas (alias de screenPageViews)

Conversiones y Revenue

• conversions - Total de conversiones
• totalRevenue - Ingresos totales
• purchaseRevenue - Ingresos de compras
• transactions - Número de transacciones
• averagePurchaseRevenue - Valor promedio de compra

💡 Ejemplos de Uso

// ❌ INCORRECTO (métricas GA3)
{
  metrics: ["users", "pageviews", "goalCompletionsAll"]
}

// ✅ CORRECTO (métricas GA4)
{
  metrics: ["activeUsers", "screenPageViews", "conversions"]
}

Desarrollo

npm install
npm run build
npm test

Changelog

Ver CHANGELOG.md para el historial completo de cambios.

Para más información, consulta CLAUDE.md