Umami MCP server

Servidor MCP que expone Umami analytics (Cloud + autoalojado)

Documentación

Servidor MCP de Umami

Servidor MCP que expone análisis de solo lectura desde la API de Umami Cloud actual y Umami 3.x autoalojado.

Matriz de soporte

Implementación	Soporte	Raíz de API	Autenticación
Umami Cloud (actual)	Compatible	`https://api.umami.is/v1`	Clave de API
Umami 3.x autoalojado	Compatible	`https://host.example/api`	Nombre de usuario/contraseña
Umami 2.x autoalojado	No compatible; cualquier integración futura será separada	—	—
Umami 1.x	No compatible	—	—

El sufijo /v1 pertenece a la URL de API de Cloud actual. No significa que este servidor admita la versión 1 de la aplicación Umami autoalojada.

Requisitos y comando de ejecución

Python 3.11+
uv

Ejecute el paquete publicado directamente:

uvx umami-mcp-server

Configuración

Variables de entorno:

UMAMI_API_KEY: clave de API de Umami Cloud.
UMAMI_USERNAME: nombre de usuario de Umami 3.x autoalojado.
UMAMI_PASSWORD: contraseña de Umami 3.x autoalojado.
UMAMI_API_BASE: opcional; el valor predeterminado es https://api.umami.is/v1. Para implementaciones autoalojadas, establezca la raíz de API incluyendo /api.

Elija exactamente un modo de autenticación: una clave de API de Cloud o nombre de usuario y contraseña autoalojados. Las claves de API de Cloud usan el esquema documentado Authorization: Bearer; el Umami 3.x autoalojado estándar no admite claves de API.

Ejemplo de configuración de MCP para Cloud:

{
  "mcp": {
    "umami": {
      "type": "local",
      "command": ["uvx", "umami-mcp-server"],
      "environment": {
        "UMAMI_API_KEY": "YOUR_UMAMI_CLOUD_API_KEY",
        "UMAMI_API_BASE": "https://api.umami.is/v1"
      },
      "enabled": true
    }
  }
}

Umami 3.x autoalojado:

{
  "mcp": {
    "umami": {
      "type": "local",
      "command": ["uvx", "umami-mcp-server"],
      "environment": {
        "UMAMI_USERNAME": "YOUR_USERNAME",
        "UMAMI_PASSWORD": "YOUR_PASSWORD",
        "UMAMI_API_BASE": "https://your-umami.example/api"
      },
      "enabled": true
    }
  }
}

Herramientas

get_websites: devuelve una página de sitios web. page >= 1 y 1 <= page_size <= 100.
get_stats: resumen de páginas vistas, visitantes, visitas, rebotes, tiempo total y comparación.
get_pageviews: series temporales de páginas vistas y sesiones.
get_metrics: métricas compactas o ampliadas. 1 <= limit <= 500 y 0 <= offset <= 10000.
get_active: visitantes activos actuales.

Cada website_id, segmento e identificador de cohorte se valida como UUID antes de que se envíe una solicitud HTTP.

Rangos de tiempo

Los parámetros de fecha y hora aceptan fechas y horas ISO. Los valores sin zona horaria se interpretan como UTC. Las cuatro reglas de rango son:

Entradas	Rango
ninguna	ahora menos siete días → ahora
solo `end_at`	siete días antes de `end_at` → `end_at`
solo `start_at`	`start_at` → ahora
ambas	rango explícito

El final debe ser posterior al inicio. Las unidades de páginas vistas son minute, hour, day, month, y year. Las zonas horarias deben ser nombres IANA válidos como UTC o Europe/Rome. Las comparaciones son prev o yoy.

Métricas y filtros

Tipos de métricas:

path, fullPath, entry, exit, referrer, domain, title, query,
event, tag, hostname, utmSource, utmMedium, utmCampaign,
utmContent, utmTerm, browser, os, device, screen, language,
country, city, region, distinctId, channel

Filtros documentados de Umami 3:

path, referrer, title, query, browser, os, device, country,
region, city, language, hostname, tag, event, distinctId,
utmSource, utmMedium, utmCampaign, utmContent, utmTerm,
segment, cohort

La entrada de la herramienta usa snake_case para distinct_id y los filtros UTM; el servidor serializa los nombres camelCase ascendentes automáticamente.

Fiabilidad y errores seguros

Se comparte un cliente HTTP y un grupo de conexiones para la vida útil del servidor MCP. Los tokens del modo de inicio de sesión se comparten, el inicio de sesión/actualización concurrente está sincronizado y una solicitud puede realizar como máximo tres envíos de análisis y una actualización de token. Las solicitudes GET reintentan solo fallos de red, tiempos de espera, límites de velocidad y respuestas transitorias de 500, 502, 503 y 504. Retry-After se respeta hasta 60 segundos.

Los errores se exponen como categorías controladas: autenticación, límite de velocidad, tiempo de espera, red, fallo ascendente y respuesta no válida. Los mensajes públicos y los registros excluyen cuerpos de respuesta, credenciales, encabezados, URL de consulta completas y valores de excepción HTTP/Pydantic sin procesar.

Caché y observabilidad

En la revisión actual de MCP, el catálogo estático tools/list tiene una sugerencia pública de caché de cinco minutos. El orden de las herramientas y el contenido del esquema son deterministas, y el catálogo no contiene datos de Umami, IDs de sitios web ni credenciales. La serialización del protocolo heredado permanece sin cambios y no incluye campos de caché.

El SDK de MCP ya rastrea las operaciones MCP entrantes. Umami MCP Server agrega un tramo hijo para cada solicitud de análisis lógico de Umami, un tramo hijo de inicio de sesión cuando es necesario, y métricas para duración, errores, reintentos, límites de velocidad y actualizaciones de token. Solo se propaga el contexto de seguimiento W3C a Umami; el equipaje de MCP no se reenvía.

El paquete base usa solo la API de OpenTelemetry, por lo que la instrumentación permanece sin operación sin un SDK y exportador. Instale la pila opcional con umami-mcp-server[otel], configúrela externamente, o desactívela explícitamente con OTEL_SDK_DISABLED=true. Consulte la guía de observabilidad para la configuración, nombres exportados, política de redacción, y ejemplos de OTLP.

Desarrollo

uv sync --dev
uv run ruff format . --check
uv run ruff check .
uv run pyright
uv run pytest

La prueba de contrato de Cloud en vivo opcional requiere UMAMI_LIVE_CLOUD_API_KEY y UMAMI_LIVE_CLOUD_WEBSITE_ID; UMAMI_LIVE_CLOUD_API_BASE puede anular la raíz de Cloud predeterminada.