Servidor MCP de Umami

Servidor MCP de solo lectura para analíticas de Umami. Se comunica directamente con la API REST de Umami a través de HTTP, soporta principalmente Umami autohospedado y también funciona con claves de API de Umami Cloud.

Este repositorio está diseñado para que los agentes de nivel superior puedan solicitar analíticas sin tener que volver a leer la documentación de Umami cada vez. Sin automatización de navegador, sin scraping de DOM, sin operaciones de escritura.

Características

• Herramientas MCP de solo lectura para las consultas de analíticas de Umami más comunes

• Dos modos de autenticación:

  • UMAMI_API_KEY

  • UMAMI_USERNAME + UMAMI_PASSWORD

• Caché de token de portador (bearer token) en memoria para instalaciones autohospedadas

• Re-inicio de sesión automático y un reintento en caso de 401 para el modo de usuario/contraseña

• Se aceptan tanto cadenas de tiempo ISO como marcas de tiempo en milisegundos

• Manejo de filtros compartido en estadísticas, vistas de página, desgloses y series de eventos

• TypeScript estricto con módulos pequeños y mantenibles

• Salida de herramientas estructurada y clara con categorías de error explícitas

Requisitos

• Node.js >= 20

• pnpm >= 10

Instalación

Desde npm:

npm install -g umami-analytics-mcp

O ejecútalo sin instalar:

npx -y umami-analytics-mcp

Para desarrollo local en este repositorio:

pnpm install

Configuración

Crea un archivo .env a partir de .env.example.

cp .env.example .env

Completa una de las siguientes opciones de autenticación:

1. Modo de clave de API

UMAMI_API_URL=https://api.umami.is/v1
UMAMI_API_KEY=your-api-key
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

2. Modo de usuario/contraseña para autohospedado

UMAMI_API_URL=https://umami.example.com/api
UMAMI_USERNAME=admin
UMAMI_PASSWORD=secret
UMAMI_DEFAULT_TIMEZONE=Asia/Shanghai

Notas:

• UMAMI_API_URL debe apuntar a la base de la API, no solo al origen del sitio.

• Si se establecen tanto UMAMI_API_KEY como el usuario/contraseña, UMAMI_API_KEY tiene prioridad.

• UMAMI_DEFAULT_TIMEZONE se utiliza cuando una herramienta admite zona horaria y tú la omites.

Ejecución local

Modo de desarrollo:

pnpm dev

Compilar y ejecutar:

pnpm build
pnpm start

El servidor utiliza el transporte stdio de MCP, por lo que permanece conectado a stdin/stdout hasta que el cliente se desconecta.

Si se instala desde npm, el comando equivalente es:

umami-analytics-mcp

Prueba

pnpm test
pnpm build

También existe una plantilla de prueba de integración con la API real que se omite por defecto:

UMAMI_INTEGRATION_TEST=1 pnpm test:integration

Inspector MCP

Compila primero:

pnpm build

Luego lanza el Inspector MCP oficial contra el servidor compilado:

npx @modelcontextprotocol/inspector node dist/cli.js

Para recarga en caliente durante el desarrollo, esto también funciona:

npx @modelcontextprotocol/inspector pnpm dev

Si deseas probar la ruta del paquete publicado en su lugar, usa:

npx @modelcontextprotocol/inspector npx -y umami-analytics-mcp

Asegúrate de que las mismas variables de entorno de Umami estén disponibles para el proceso del Inspector.

Llamadas de prueba recomendadas en el Inspector:

1. umami_ping

2. umami_list_websites

3. umami_get_stats

4. umami_get_breakdown

Herramientas

umami_ping

Valida la configuración y la autenticación.

Ejemplo:

{}

umami_list_websites

Enumera los sitios web accesibles.

Ejemplo:

{}

umami_find_website

Búsqueda difusa por nombre de sitio web o dominio.

Ejemplo:

{
  "query": "example.com"
}

umami_get_stats

Estadísticas resumidas para un sitio web y un rango de tiempo.

Ejemplo:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-23T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "filters": {
    "path": "/pricing"
  }
}

umami_get_pageviews

Vistas de página y sesiones en series temporales.

Ejemplo:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day",
  "compare": "prev",
  "filters": {
    "path": "/blog"
  }
}

umami_get_breakdown

Filas de desglose como páginas principales, referentes, países, navegadores, dispositivos y más.

Ejemplo:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "type": "path",
  "limit": 10,
  "expanded": false
}

umami_get_active

Devuelve el recuento actual de visitantes activos.

Ejemplo:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab"
}

umami_get_events_series

Devuelve los recuentos de eventos personalizados a lo largo del tiempo.

Ejemplo:

{
  "websiteId": "8f2f8ce2-1234-4567-89ab-0123456789ab",
  "startAt": "2026-04-17T00:00:00+08:00",
  "endAt": "2026-04-23T23:59:59+08:00",
  "unit": "day"
}

Filtros compartidos

Estas herramientas admiten el mismo objeto filters:

• path

• referrer

• title

• query

• browser

• os

• device

• country

• region

• city

• hostname

Manejo de errores

Los errores de las herramientas se devuelven como resultados estructurados de herramientas MCP con estas categorías:

• config_missing

• auth_failed

• website_not_found

• umami_http_error

• network_timeout

• network_error

• invalid_input

Montaje en cualquier cliente MCP stdio

Cualquier cliente MCP basado en stdio puede ejecutar este servidor con:

• command: npx

• args: ["-y", "umami-analytics-mcp"]

• env: tus variables de Umami

Fragmento JSON de ejemplo para clientes que utilizan un objeto mcpServers:

{
  "mcpServers": {
    "umami": {
      "command": "npx",
      "args": ["-y", "umami-analytics-mcp"],
      "env": {
        "UMAMI_API_URL": "https://umami.example.com/api",
        "UMAMI_USERNAME": "admin",
        "UMAMI_PASSWORD": "secret",
        "UMAMI_DEFAULT_TIMEZONE": "Asia/Shanghai"
      }
    }
  }
}

Para una versión local no publicada, aún puedes apuntar directamente al archivo compilado:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/cli.js"]
    }
  }
}

Publicar en npm

Este repositorio está estructurado ahora como un paquete CLI de npm.

Flujo de lanzamiento recomendado:

pnpm test
pnpm build
pnpm pack --dry-run
npm login
pnpm publish

Notas:

• El nombre del paquete está configurado como umami-analytics-mcp porque umami-mcp ya está ocupado en npm.

• La license actual es UNLICENSED como marcador de posición seguro. Reemplázala antes de un lanzamiento público real de código abierto si deseas una licencia permisiva.

• Si más tarde publicas bajo tu propio ámbito (scope) de npm, cambia solo el campo name en package.json.

Documentación interna

• Resumen de la API utilizado por este repositorio: docs/umami-api.md