Umami MCP Server

Un servidor Model Context Protocol para Umami Analytics. Pregunta a Claude, Cursor o cualquier cliente MCP sobre tu tráfico — y deja que cree y gestione sitios web — mientras tus credenciales permanecen en tu propia máquina.

"Which pages drove the most visitors last month, and where did that traffic come from?"
"Build a funnel from /pricing to /signup to /welcome for the last 30 days."
"Add analytics for my new site blog.example.com and give me the tracking snippet."

Por qué existe esto

Umami no tiene un servidor MCP oficial. Existen varios comunitarios, y si solo quieres una amplia cobertura de la API, deberías mirar primero 0xtlt/umami-mcp — envuelve más de la API que este. Algunos de los servidores más antiguos (jakeyShakey, mikusnuz, mittwald, Macawls) fueron escritos para la API v2 y fallan en una instancia moderna, porque v3 renombró cosas sin alias:

Este servidor existe para dos cosas que los demás no hacen:

1. Cobertura completa y verificada de informes v3. Los siete tipos de informes v3 — embudo, retención, recorrido, objetivo, ingresos, atribución y UTM — se probaron contra una instancia real de Umami 3.3.1. El sobre del informe es fácil de equivocar: las fechas van en parameters como cadenas ISO-8601, no en filters, ni como los milisegundos de época que usa el resto de la API. La atribución usa first-click / last-click, no las grafías camelCase que adivinarías.

2. Un modelo de capacidades en lugar de un booleano. Ver más abajo.

Related MCP server: Umami MCP Server

Modelo de seguridad

Un servidor MCP de análisis guarda una credencial que puede leer cada sesión de visitante que hayas registrado — y, si se lo permites, borrarlo todo. El diseño se deriva de eso.

Tus credenciales nunca salen de tu entorno. La configuración se lee solo del entorno del proceso. No hay telemetría, ni llamadas a casa, ni relé alojado. El único host al que este servidor contacta es el UMAMI_URL que configures. Si lo auto-alojas, nada de tus análisis llega jamás a un tercero — incluyendo al autor de este software.

Desconfía de cualquier Umami MCP que ofrezca un endpoint alojado al que apuntes tu instancia. El Umami autoalojado no tiene claves API, así que el alojamiento "conveniente" significa enviar tu contraseña de administrador por correo al servidor de otra persona.

Menor privilegio por defecto. El servidor arranca en modo read. Ampliarlo es un acto deliberado:

Las herramientas retenidas no se registran en absoluto, por lo que nunca aparecen en la lista de herramientas del modelo. Esta es la parte que difiere de un indicador READONLY=true: una herramienta que nunca se anunció no puede ser invocada por una instrucción inyectada en el prompt oculta, por ejemplo, en una cadena de referer o en un título de página dentro de tus propios datos de analítica. No hay comprobación en tiempo de ejecución que olvidar o eludir, porque no hay herramienta.

Las acciones destructivas requieren una confirmación escrita verificada contra la realidad. umami_delete_website toma un argumento confirmDomain, obtiene el registro en vivo y se niega a menos que coincidan. Un modelo que intente el UUID de un sitio web equivocado recibe un error, no un conjunto de datos borrado.

Las credenciales permanecen fuera de la configuración del cliente. En lugar de requerir tu contraseña dentro de ~/.claude.json o mcp.json, el servidor la lee de un archivo que controlas en ~/.config/umami-mcp/env, y avisa si ese archivo es legible por otros usuarios. Ver Credenciales.

Los secretos se eliminan de la salida. La salida de MCP fluye hacia un modelo y a menudo hacia una transcripción de chat, que no se puede deshacer. Las contraseñas, los tokens de portador y los JWT se redactan de cada error y respuesta antes de salir del proceso.

Se niega a filtrar credenciales por la red. Se rechaza el HTTP en texto plano a un host remoto al iniciar; solo se permite para localhost, para desarrollo local.

Instalación

Tres formas de ejecutarlo. El autoalojamiento es la opción por defecto y la recomendada — la instancia alojada existe para que puedas probarlo en dos minutos sin clonar nada.

Si lo auto-alojas y quieres usarlo en Claude web, ejecútalo con UMAMI_MCP_OAUTH=true detrás de tu propio dominio — entonces nada tuyo toca la infraestructura de nadie más.

1. Usar la instancia alojada (nada que instalar)

Añade un conector personalizado en Claude apuntando a:

https://umami-mcp.asif.dev/mcp

Se te pedirá tu propia URL de Umami y el inicio de sesión en una pantalla de consentimiento. Ver Claude web, Cowork y Claude Code en web para saber cómo se manejan las credenciales.

2. Desde el código fuente

git clone https://github.com/Asif2BD/umami-mcp.git
cd umami-mcp
npm install && npm run build

Luego configura las credenciales y regístralo con tu cliente:

claude mcp add umami --scope user -- node "$PWD/dist/index.js"

Requiere Node 20 o superior.

3. Docker

git clone https://github.com/Asif2BD/umami-mcp.git
cd umami-mcp
cp .env.example .env    # then edit .env
docker compose up -d

npm: aún no publicado. Cuando lo esté, npx -y @asif2bd/umami-mcp reemplazará el paso de clonar y compilar de arriba. Hasta entonces usa el código fuente o Docker.

Credenciales

El Umami autoalojado no tiene claves API, por lo que la credencial que guarda este servidor es una contraseña de cuenta real. Los clientes MCP normalmente quieren que esté incrustada en su JSON de configuración — ~/.claude.json, mcp.json y similares — que son ampliamente legibles, se pegan en incidencias y pantallas compartidas, y algunos clientes los sincronizan entre máquinas.

Así que este servidor lee las credenciales de un archivo que tú controlas. Créalo una vez:

mkdir -p ~/.config/umami-mcp
cat > ~/.config/umami-mcp/env <<'EOF'
UMAMI_URL=https://analytics.example.com
UMAMI_USERNAME=mcp-bot
UMAMI_PASSWORD=your-password
UMAMI_MCP_MODE=read
EOF
chmod 600 ~/.config/umami-mcp/env

El servidor lo carga automáticamente. Avisa al iniciar si el archivo es legible por otros usuarios.

Orden de búsqueda — el primer archivo encontrado gana, y las variables de entorno reales siempre tienen prioridad sobre el archivo, así que aún puedes pasar ajustes desde la configuración del cliente cuando quieras:

1. $UMAMI_MCP_ENV_FILE, si está definida

2. ~/.config/umami-mcp/env (o $XDG_CONFIG_HOME/umami-mcp/env)

3. ./.env en el directorio de trabajo

Conecta tu cliente

Claude Code

Con el archivo de credenciales de arriba, el registro no lleva ningún secreto:

claude mcp add umami --scope user -- node ~/umami-mcp/dist/index.js

Usa la ruta absoluta a tu clon. Si tu Node vive bajo nvm, da también la ruta completa del intérprete, ya que los clientes MCP no cargan tu perfil de shell:

claude mcp add umami --scope user -- ~/.nvm/versions/node/v22.22.0/bin/node ~/umami-mcp/dist/index.js

Claude Desktop / Cursor / VS Code

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

Si prefieres tenerlo todo en un solo lugar, las variables de entorno siguen funcionando y tienen prioridad sobre el archivo:

{
  "mcpServers": {
    "umami": {
      "command": "node",
      "args": ["/absolute/path/to/umami-mcp/dist/index.js"],
      "env": {
        "UMAMI_URL": "https://analytics.example.com",
        "UMAMI_USERNAME": "mcp-bot",
        "UMAMI_PASSWORD": "your-password"
      }
    }
  }
}

Comprueba que funciona

Pide a tu cliente que ejecute umami_whoami. Informa de la instancia, la cuenta y el modo de permiso — la forma más rápida de confirmar la conexión y ver cuánto puede hacer el servidor:

{
  "instance": "https://analytics.example.com",
  "authenticatedAs": "mcp-bot",
  "role": "admin",
  "serverMode": "read",
  "destructiveOperations": "disabled"
}

Luego prueba: "Lista mis sitios web de Umami", o "¿Cuáles fueron mis páginas principales la semana pasada?"

Claude web, Cowork y Claude Code en web

Esos clientes no pueden lanzar un proceso local, así que necesitan un servidor MCP HTTPS público — y su interfaz de conector acepta solo OAuth, sin campo para un token de portador estático o cabecera personalizada.

Alojarlo de la manera obvia, con un conjunto de credenciales de Umami incrustadas y sin autenticación, convierte la URL en un proxy abierto a ese Umami. Así que este servidor usa OAuth en su lugar, y lo hace sin convertirse en un almacén de credenciales.

Usar la instancia alojada

Añade un conector personalizado en Claude con esta URL:

https://umami-mcp.asif.dev/mcp

Claude se registra a sí mismo, te envía a una pantalla de consentimiento y te pide tu propia URL de Umami, nombre de usuario y contraseña. Nada se comparte con otros usuarios del host.

Aloja el tuyo propio

UMAMI_MCP_OAUTH=true
UMAMI_MCP_TRANSPORT=http
UMAMI_MCP_ISSUER=https://mcp.example.com      # public HTTPS URL of this server
UMAMI_MCP_TOKEN_KEY=<32 random bytes>          # keep stable; see below
UMAMI_MCP_TOKEN_TTL=2592000                    # 30 days

Genera la clave una vez y consérvala:

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

Define también UMAMI_URL para fijar a cada usuario a una instancia en lugar de dejar que elijan.

Cómo se manejan las credenciales

La pantalla de consentimiento verifica las credenciales contra la instancia de Umami que nombró el usuario, luego las sella en el token de acceso con AES-256-GCM. El servidor no mantiene ninguna tabla de sesión ni almacena credenciales: cada solicitud descifra el token, construye un servidor MCP limitado a ese único usuario, atiende la llamada y lo descarta.

El compromiso honesto: quien tenga UMAMI_MCP_TOKEN_KEY puede descifrar cualquier token que capture. Trátala como el valor más sensible del despliegue. Rotarla invalida todos los tokens emitidos, que es el control de radio de explosión previsto.

Las herramientas destructivas nunca se exponen a través de OAuth, sea cual sea el permiso que elija el usuario. Su guardia de confirmación escrita asume un operador local que puede ver lo que va a eliminar, y a un llamante remoto no se le puede mostrar eso.

Ejecutarlo como un servicio HTTP simple

Configura UMAMI_MCP_TRANSPORT=http sin UMAMI_MCP_OAUTH para un endpoint de un solo inquilino en /mcp, además de /health.

En este modo el servidor no tiene autenticación propia. Cualquiera que pueda alcanzar el puerto puede usar tus credenciales de Umami. Mantenlo en loopback y haz un túnel hacia él:

ssh -N -L 3334:127.0.0.1:3334 you@your-server
claude mcp add --transport http umami http://127.0.0.1:3334/mcp

El servidor avisa al iniciar cuando está enlazado a algo que no sea loopback.

Herramientas

Rangos de tiempo

Todas las herramientas de analítica aceptan una abreviatura period — 24h, 7d, 30d, 12m, today, yesterday — en lugar de milisegundos epoch. Los modelos son fiables cuando se trata de «últimos 30 días» y poco fiables con la aritmética de marcas de tiempo; un epoch mal calculado devuelve datos de la ventana equivocada sin dar error. Los startAt/endAt explícitos en milisegundos epoch siguen funcionando y tienen prioridad.

Configuración

Consulta .env.example para ver todas las opciones. Lo esencial:

Configuración recomendada

Crea una cuenta de Umami dedicada para el servidor MCP en lugar de reutilizar tu inicio de sesión de administrador, y dale acceso únicamente a los sitios web que necesite. De este modo, si la credencial llega a exponerse, el radio de explosión será una cuenta de bot que puedes eliminar, no tu administrador.

Compatibilidad

Verificado con Umami 3.3.1 (autoalojado, PostgreSQL). Umami Cloud funciona mediante UMAMI_API_KEY. Umami v2 no es compatible: los tipos de métricas renombrados anteriormente implican que v2 y v3 necesitan clientes distintos, y este apunta a v3.

Desarrollo

npm install
npm run build
npm test          # unit tests, no network required

test/e2e.mjs y test/write-e2e.mjs ejecutan el servidor compilado a través de un cliente MCP real contra una instancia en vivo. La prueba de escritura crea un sitio web desechable en un dominio .invalid y lo elimina de nuevo; apúntala a una instancia que no sea de producción.

Contribuciones

Las issues y las pull requests son bienvenidas. Umami v3 expone alrededor de 127 rutas de API y este servidor cubre las más útiles —la reproducción de sesiones, los mapas de calor, los píxeles, el seguimiento de enlaces, los paneles y los segmentos siguen sin mapearse—. Si añades herramientas, sé honesto con el nivel y las marcas destructive, porque todo el modelo de seguridad se sustenta en ellos.

Si el equipo de Umami quisiera adoptar esto, hacer un fork o subirlo al upstream, por favor abre una issue; ese es el resultado para el que se construyó.

Licencia

MIT © M Asif Rahman