Ntfy MCP Server

Envía notificaciones push a través del servicio ntfy, permitiendo que LLMs y agentes de IA notifiquen a tus dispositivos.

GitHub

Prueba este MCPPatrocinado

Documentación

ntfy-mcp-server

Envía, gestiona y reproduce notificaciones push de ntfy mediante MCP. STDIO o HTTP Streamable.

4 herramientas • 1 recurso

Resumen

Notificaciones push a través de la API HTTP pub/sub de ntfy. Publica, actualiza y gestiona notificaciones, consulta el historial de temas en caché y busca códigos cortos de emojis para etiquetas desde cualquier cliente MCP. Se ejecuta como un proceso stdio o como un servidor HTTP Streamable local.

Herramientas

Herramienta	Descripción
`ntfy_publish_message`	Envía o actualiza una notificación push en un tema de ntfy.
`ntfy_manage_message`	Borra o elimina una notificación enviada previamente mediante `sequence_id`.
`ntfy_fetch_messages`	Consulta mensajes en caché de uno o más temas con filtros opcionales.
`ntfy_search_emoji_tags`	Busca códigos cortos de emojis de etiquetas de ntfy para usar en `tags`.

Recursos

Recurso	Descripción
`ntfy://{topic}`	Instantánea de un tema: los últimos 20 mensajes de la última hora, más la URL del navegador del tema.

ntfy_fetch_messages cubre los mismos datos del tema con ventanas y filtros personalizados cuando los valores predeterminados fijos del recurso no son suficientes.

Referencia de capacidades

`ntfy_publish_message` _herramienta

Los temas se crean en la primera publicación: trata el nombre del tema como un secreto; cualquiera que lo conozca puede publicar o suscribirse
Cobertura completa de parámetros de publicación: title, priority (1–5), tags, click, attach, icon, filename, markdown, delay, email, call, cache, firebase; el cuerpo del mensaje está limitado a 4096 bytes (los caracteres no ASCII cuestan más), el cuerpo vacío se establece de forma predeterminada en el servidor como triggered
Hasta tres botones de acción discriminados (view, broadcast, http, copy) por mensaje
Actualiza o reemplaza un mensaje enviado previamente pasando el sequence_id original
La anulación base_url por llamada reenvía las credenciales solo cuando coincide con un servidor registrado (NTFY_BASE_URL o una entrada NTFY_SERVERS); de lo contrario, la solicitud sale sin autenticación
Las publicaciones que llevan email, call o un botón de acción broadcast/http piden al usuario que confirme el destino específico primero: la llamada devuelve una solicitud de confirmación y solo envía cuando se reemite con la respuesta

`ntfy_manage_message` _herramienta

operation: clear marca la notificación como leída y la descarta (los suscriptores ven message_clear); delete la elimina del cajón (los suscriptores ven message_delete)
Solo anexión: el mensaje original permanece en la caché; reemitir la misma operación es seguro, aunque se dispara un evento nuevo en cada llamada
Cada llamada pide al usuario que confirme el tema, sequence_id y la operación antes de que se dispare el evento: la primera llamada devuelve esa solicitud de confirmación, y rechazarla falla con consent_declined
ntfy.sh acepta un sequence_id desconocido sin error; las implementaciones de ntfy más estrictas devuelven un fallo not_found en su lugar

`ntfy_fetch_messages` _herramienta

Devuelve una instantánea, no una transmisión en vivo: úsala para confirmar la entrega, reproducir alertas perdidas o auditar la actividad del tema
Consultas de múltiples temas separados por comas (p. ej., alerts,backups,phil_alerts)
Filtra por since (duración / marca de tiempo / ID de mensaje / all / latest), priority, tags, id, title, message, solo programados
Ventana predeterminada 10m, límite predeterminado de 20 mensajes por respuesta, tope máximo de 100: las ventanas que superan el límite conservan los limit mensajes más recientes, listados de más antiguo a más nuevo
Los cuerpos largos se truncan a ~500 caracteres con messageTruncated que informa el recuento descartado; vuelve a consultar con un mensaje id para leer ese mensaje completo

`ntfy_search_emoji_tags` _herramienta

Coincidencia de subcadena contra nombres de etiquetas, sin distinguir mayúsculas de minúsculas; omite query para listar la referencia desde el inicio en su orden documentado
limit predeterminado 25, máximo 200; offset pagina más allá del límite usando el totalCount devuelto
Las cadenas tag devueltas se conectan directamente al campo tags de ntfy_publish_message

`ntfy://{topic}` _recurso

Instantánea fija: los últimos 20 mensajes de la última hora, más la URL del navegador del tema; misma forma de mensaje normalizada que ntfy_fetch_messages (marcas de tiempo ISO 8601, truncamiento de cuerpo de ~500 caracteres)
Para ventanas, filtros o reproducción personalizados, usa ntfy_fetch_messages en su lugar

Características

Construido sobre @cyanheads/mcp-ts-core: transportes stdio y HTTP Streamable, autenticación conectable (none / jwt / oauth), almacenamiento intercambiable (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), registro estructurado con rastreo opcional de OpenTelemetry.

Específico de ntfy:

Envuelve la API HTTP de ntfy con un cliente consciente de reintentos (withRetry + tiempo de espera por solicitud)
Autenticación con ámbito por servidor: las credenciales se vinculan a cada URL base registrada (NTFY_BASE_URL o una entrada NTFY_SERVERS); modos de token portador / autenticación básica mutuamente excluyentes validados en la carga de configuración; una anulación base_url por llamada reenvía la autenticación solo cuando coincide con un servidor registrado
Confirmación del usuario antes de efectos secundarios que dejan el cajón de notificaciones: un borrado/eliminación, o una publicación que lleva email, call o un botón de acción broadcast/http — aplicada tanto en stdio como en HTTP Streamable
Protección SSRF opcional en anulaciones base_url (NTFY_BLOCK_PRIVATE_HOSTS): bloquea loopback, RFC 1918, malla RFC 6598, enlace local y equivalentes IPv6, luego rechaza redirecciones; los servidores registrados están exentos
Referencia de etiquetas de emojis incluida, regenerada desde el docs/ntfy/emojis.md ascendente mediante scripts/build-emoji-tags.ts

Salida amigable para agentes:

Procedencia: ntfy_publish_message y ntfy_manage_message devuelven el tema, ID y marca de tiempo resueltos; ntfy_fetch_messages también devuelve el since resuelto y los filtros aplicados
Salidas discriminadas: códigos reason tipados (consent_declined, forbidden_topic, rate_limited, not_found, payload_too_large y más) en el contrato de error de cada herramienta permiten a los llamadores ramificar según el modo de fallo en lugar de analizar el texto del error
Orientación de truncamiento y paginación: ntfy_fetch_messages y ntfy_search_emoji_tags informan un indicador truncated más un notice que nombra el siguiente paso exacto (ampliar since, aumentar limit, avanzar offset) en lugar de descartar resultados silenciosamente

Primeros pasos

Agrega lo siguiente al archivo de configuración de tu cliente MCP. El ntfy.sh público funciona de inmediato sin cuenta; para temas protegidos, genera un token de acceso en https://ntfy.sh/account.

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["ntfy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NTFY_DEFAULT_TOPIC": "your-topic-name"
      }
    }
  }
}

O con npx (sin necesidad de Bun):

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ntfy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NTFY_DEFAULT_TOPIC": "your-topic-name"
      }
    }
  }
}

O con Docker:

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "NTFY_DEFAULT_TOPIC=your-topic-name",
        "ghcr.io/cyanheads/ntfy-mcp-server:latest"
      ]
    }
  }
}

Para HTTP Streamable, configura el transporte e inicia el servidor:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NTFY_DEFAULT_TOPIC=your-topic bun run start:http
# Server listens at http://127.0.0.1:3010/mcp

Requisitos previos

Bun v1.4.0 o superior (o Node.js v24+).
Un nombre de tema en un servidor ntfy. El ntfy.sh público no requiere cuenta; las instancias autoalojadas y los temas protegidos pueden necesitar un token portador o credenciales de autenticación básica.

Instalación

Clona el repositorio:

git clone https://github.com/cyanheads/ntfy-mcp-server.git

Navega al directorio:

cd ntfy-mcp-server

Instala las dependencias:

bun install

Configura el entorno:

cp .env.example .env
# edit .env and set NTFY_DEFAULT_TOPIC (and auth, if needed)

Configuración

Variable	Descripción	Predeterminado
`NTFY_SERVERS`	Matriz JSON de entradas `{ baseUrl, authToken? \| authUsername?+authPassword? }`: una por servidor ntfy. La primera entrada es la base predeterminada. La autenticación tiene ámbito en el `baseUrl` de la entrada; las anulaciones `base_url` por llamada que coinciden con una base registrada reenvían la autenticación de ese servidor. Úsalo cuando necesites más de un servidor autenticado en un solo proceso; tiene prioridad sobre las variables de servidor único a continuación.	—
`NTFY_BASE_URL`	Abreviatura de servidor único: URL base del servidor ntfy (sin barra final). Se usa cuando `NTFY_SERVERS` no está establecido.	`https://ntfy.sh`
`NTFY_DEFAULT_TOPIC`	Tema usado cuando una llamada de herramienta omite `topic`.	—
`NTFY_AUTH_TOKEN`	Token de acceso portador (`tk_…`) para la abreviatura de servidor único. Mutuamente excluyente con `NTFY_AUTH_USERNAME` / `NTFY_AUTH_PASSWORD`.	—
`NTFY_AUTH_USERNAME`	Nombre de usuario de autenticación básica para la abreviatura de servidor único: requerido junto con `NTFY_AUTH_PASSWORD`.	—
`NTFY_AUTH_PASSWORD`	Contraseña de autenticación básica para la abreviatura de servidor único: requerida junto con `NTFY_AUTH_USERNAME`.	—
`NTFY_REQUEST_TIMEOUT_MS`	Tiempo de espera HTTP por solicitud en milisegundos.	`15000`
`NTFY_MAX_RETRIES`	Intentos de reintento máximos para fallos transitorios ascendentes (5xx, red, 429).	`3`
`NTFY_BLOCK_PRIVATE_HOSTS`	Cuando `true`, una anulación `base_url` por llamada debe resolverse a una dirección pública, y sus redirecciones no se siguen. Los servidores registrados bajo `NTFY_SERVERS` / `NTFY_BASE_URL` están exentos, por lo que un destino LAN deliberado aún funciona. Actívalo donde los llamadores que no controlas puedan alcanzar el servidor.	`false`
`MCP_TRANSPORT_TYPE`	Transporte: `stdio` o `http`.	`stdio`
`MCP_SESSION_MODE`	Modelo de sesión HTTP: `auto`, `stateful` o `stateless`. Este servidor requiere `stateful` sobre HTTP: la solicitud de consentimiento en llamadas destructivas y salientes es una solicitud de múltiples idas y vueltas que un cliente HTTP de la era 2025 solo puede completar sobre una sesión en vivo, por lo que un inicio HTTP con `stateless` se rechaza. `auto` se resuelve a `stateful`; stdio ignora la configuración.	`stateful`
`MCP_HTTP_HOST`	Host HTTP.	`127.0.0.1`
`MCP_HTTP_PORT`	Puerto HTTP.	`3010`
`MCP_HTTP_ENDPOINT_PATH`	Ruta del punto final HTTP.	`/mcp`
`MCP_AUTH_MODE`	Modo de autenticación: `none`, `jwt` o `oauth`.	`none`
`MCP_LOG_LEVEL`	Nivel de registro (RFC 5424).	`info`
`LOGS_DIR`	Directorio para registros basados en archivos (solo Node; ignorado en Workers).	`./logs`
`OTEL_ENABLED`	Habilita instrumentación de OpenTelemetry (tramos, métricas, registros de finalización).	`false`

Consulta .env.example para la lista completa de anulaciones opcionales.

Ejecutar el servidor

Desarrollo local

Compilar y ejecutar:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Ejecutar comprobaciones y pruebas:

bun run devcheck     # Lint, format, typecheck, security, changelog sync
bun run test         # Vitest test suite
bun run lint:mcp     # Validate MCP definitions against spec

Docker

docker build -t ntfy-mcp-server .
docker run --rm -e NTFY_DEFAULT_TOPIC=your-topic -p 3010:3010 ntfy-mcp-server

El Dockerfile usa por defecto transporte HTTP, modo de sesión con estado y registra en /var/log/ntfy-mcp-server. Las dependencias de pares de OpenTelemetry se instalan por defecto: compila con --build-arg OTEL_ENABLED=false para omitirlas.

Estructura del proyecto

Directorio	Propósito
`src/index.ts`	Punto de entrada de `createApp()` — registra herramientas y recursos, inicializa servicios.
`src/config`	Análisis de variables de entorno específicas del servidor (`NTFY_*`) con Zod.
`src/mcp-server/tools`	Definiciones de herramientas (`*.tool.ts`).
`src/mcp-server/resources`	Definiciones de recursos (`*.resource.ts`).
`src/services/ntfy`	Cliente HTTP de ntfy, tipos y clasificador de errores.
`src/services/emoji-tags`	Referencia de códigos cortos de emoji incluidos y servicio de búsqueda.
`docs/ntfy`	Documentación de la API de ntfy reflejada desde el upstream (commit fijado en `SOURCES.md`).
`tests/`	Pruebas unitarias y de integración que reflejan `src/`.

Guía de desarrollo

Consulta CLAUDE.md para las pautas de desarrollo y reglas arquitectónicas. La versión corta:

Los manejadores lanzan excepciones, el framework las captura — sin try/catch en la lógica de herramientas
Usa ctx.log para registro con ámbito de solicitud, ctx.state para almacenamiento con ámbito de inquilino
Envuelve las llamadas a APIs externas: valida los datos crudos → normaliza al tipo de dominio → devuelve el esquema de salida; nunca inventes campos faltantes
Los contratos de errors[] por herramienta permanecen en línea — la repetición es intencional para la localidad

Contribuciones

Las incidencias son bienvenidas. Ejecuta las comprobaciones y pruebas antes de enviar:

bun run devcheck
bun run test

Licencia

Apache-2.0 — consulta LICENSE para más detalles.