Servidor MCP de Ntfy

Un servidor MCP (Protocolo de Contexto de Modelo) diseñado para interactuar con el servicio de notificaciones push ntfy . Permite que los LLM y los agentes de IA envíen notificaciones a sus dispositivos con amplias opciones de personalización.

Tabla de contenido

Descripción general
Características
Inicio rápido
Instalación
Configuración
Estructura del proyecto
Herramientas
Recursos
Casos de uso
Scripts disponibles
Contribuyendo
Licencia

Descripción general

Este servidor implementa el Protocolo de Contexto de Modelo (MCP), lo que permite la comunicación estandarizada entre los LLM y los sistemas externos. En concreto, proporciona una interfaz con el servicio de notificaciones push ntfy.

Ntfy es un sencillo servicio de notificaciones de publicación y suscripción basado en HTTP que permite enviar notificaciones a su teléfono o computadora mediante simples solicitudes HTTP. Con este servidor MCP, agentes LLM como Claude pueden enviarle notificaciones a través de ntfy sin necesidad de acceso HTTP directo.

┌───────────┐      ┌───────────┐      ┌───────────┐      ┌─────────┐
│ LLM Agent │ ────▶│ Ntfy MCP  │ ────▶│ Ntfy      │ ────▶│ Your    │
│ (Claude)  │      │ Server    │      │ Service   │      │ Devices │
└───────────┘      └───────────┘      └───────────┘      └─────────┘

Características

Implementación del servidor MCP: creado utilizando @modelcontextprotocol/sdk para una integración perfecta con agentes LLM.
Integración con Ntfy: proporciona una herramienta ( send_ntfy ) para enviar notificaciones con soporte para:
- Priorización de mensajes (1-5 niveles)
- Etiquetas emoji
- Acciones y botones en los que se puede hacer clic
- Archivos adjuntos
- Entrega retrasada
- Formato Markdown
Exposición de recursos: expone el tema ntfy predeterminado configurado como un recurso MCP.
TypeScript: base de código moderna y segura con definiciones de tipos integrales.
Registro estructurado: utiliza winston y winston-daily-rotate-file para obtener registros detallados y rotativos.
Gestión de la configuración: utiliza dotenv para una fácil configuración basada en el entorno.
Scripts de utilidad: incluye scripts para limpiar artefactos de compilación y generar documentación de la estructura de directorios.
Manejo de errores y seguridad: implementa un manejo robusto de errores, desinfección de entrada ( sanitize-html ) y filtros de seguridad ( xss-filters ).

Inicio rápido

Prerrequisitos:
- Node.js (v16+)
- npm o hilo
- Un cliente compatible con MCP (Claude Desktop, Cline, etc.)
Instalar y ejecutar:
# Option 1: Install via npm npm install -g ntfy-mcp-server # Option 2: Clone repository and build git clone https://github.com/cyanheads/ntfy-mcp-server.git cd ntfy-mcp-server npm install npm run build # Create .env file (optional but recommended) cp .env.example .env # Edit .env to set NTFY_DEFAULT_TOPIC # Start the server npm start
Agregar a la configuración del cliente MCP: agregue el servidor a su archivo de configuración del cliente MCP (consulte Configuración )
Usar la herramienta: Una vez conectado, puedes usar la herramienta send_ntfy para enviar notificaciones.

Instalación

Opción 1: Paquete NPM (recomendado)

Instalar el paquete globalmente:
npm install -g ntfy-mcp-server
Esto instalará el servidor globalmente, haciéndolo disponible como una herramienta de línea de comandos.
O instalarlo localmente en su proyecto:
npm install ntfy-mcp-server
Cuando se instala localmente, puedes ejecutarlo a través de npx o desde el nodo.

Opción 2: Desde la fuente

Clonar el repositorio:
git clone https://github.com/cyanheads/ntfy-mcp-server.git cd ntfy-mcp-server
Instalar dependencias:
npm install
Construir el proyecto:
npm run build

Configuración

Variables de entorno

Cree un archivo .env en la raíz del proyecto basado en .env.example :

# Ntfy Configuration
NTFY_BASE_URL=https://ntfy.sh  # Optional: Base URL of your ntfy instance
NTFY_DEFAULT_TOPIC=your_default_topic # Optional: Default topic if none specified in requests

# Application Configuration
LOG_LEVEL=info # Optional: Logging level (debug, info, warn, error)
NODE_ENV=development # Optional: Environment (development, production)

Configuración del cliente MCP

Para la extensión Cline VSCode

Agregue la siguiente configuración a su archivo de configuración de Cline MCP (generalmente ubicado en ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json en macOS):

Si se instala globalmente:

{
  "mcpServers": {
    "ntfy": {
      "command": "ntfy-mcp-server",
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Si se instala desde la fuente:

{
  "mcpServers": {
    "ntfy": {
      "command": "node",
      "args": ["/path/to/ntfy-mcp-server/dist/index.js"],
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Para la aplicación de escritorio de Claude

Agregue la siguiente configuración a su archivo de configuración de Claude Desktop (generalmente ubicado en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

Si se instala globalmente:

{
  "mcpServers": {
    "ntfy": {
      "command": "ntfy-mcp-server",
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Si se instala desde la fuente:

{
  "mcpServers": {
    "ntfy": {
      "command": "node",
      "args": ["/path/to/ntfy-mcp-server/dist/index.js"],
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

Para la instalación del código fuente, reemplace /path/to/ntfy-mcp-server/dist/index.js con la ruta absoluta del archivo del servidor compilado. Ajuste las variables env según sea necesario para su configuración.

Configuración de Ntfy

Instale la aplicación ntfy en sus dispositivos desde ntfy.sh o las tiendas de aplicaciones
Suscríbete a tu tema en la aplicación
Utilice el mismo tema en la configuración de su servidor MCP

Estructura del proyecto

.
├── .env.example            # Example environment variables
├── .gitignore              # Git ignore patterns
├── LICENSE                 # Project license (Apache-2.0)
├── package.json            # Project metadata and dependencies
├── tsconfig.json           # TypeScript compiler configuration
├── docs/
│   └── tree.md             # Auto-generated directory structure
├── logs/                   # Runtime logs (created automatically)
├── scripts/                # Utility scripts
│   ├── clean.ts            # Cleans build artifacts and logs
│   └── tree.ts             # Generates the docs/tree.md file
└── src/                    # Source code
    ├── index.ts            # Main server entry point
    ├── config/             # Configuration loading
    ├── mcp-server/         # MCP server logic, tools, and resources
    │   ├── resources/      # MCP resource implementations
    │   ├── tools/          # MCP tool implementations
    │   └── utils/          # MCP-specific utilities
    ├── services/           # External service integrations (ntfy)
    ├── types-global/       # Global type definitions
    └── utils/              # General utility functions

Herramientas

`send_ntfy`

Envía un mensaje de notificación a través del servicio ntfy.

Argumentos clave:

Parámetro	Tipo	Requerido	Descripción
`topic`	cadena	Sí	El tema de ntfy para publicar.
`message`	cadena	Sí	El contenido principal de la notificación (máximo 4096 bytes).
`title`	cadena	No	Título de la notificación (máximo 250 bytes).
`tags`	cadena[]	No	Emojis o palabras clave para categorizar (p. ej., `["warning", "robot"]` ). Máximo 5.
`priority`	entero	No	Prioridad del mensaje: 1=mín., 2=baja, 3=predeterminada, 4=alta, 5=máx.
`click`	cadena	No	URL para abrir cuando se hace clic en la notificación.
`actions`	formación	No	Botones de acción (ver, http, transmitir). Máximo 3.
`attachment`	objeto	No	URL y nombre de un archivo adjunto.
`email`	cadena	No	Dirección de correo electrónico a la que reenviar la notificación.
`delay`	cadena	No	Retrasar la entrega (por ejemplo, `30m` , `1h` , `tomorrow` ).
`cache`	cadena	No	Duración de la caché (por ejemplo, `10m` , `1h` , `1d` ).
`firebase`	cadena	No	Tema de Firebase Cloud Messaging (FCM) al que reenviar.
`id`	cadena	No	Identificador único para el mensaje.
`expires`	cadena	No	Caducidad del mensaje (por ejemplo, `10m` , `1h` , `1d` ).
`markdown`	booleano	No	Establezca como `true` para habilitar el formato Markdown en el mensaje.
`baseUrl`	cadena	No	Anular la URL del servidor ntfy predeterminada para esta solicitud.

Ejemplo de uso:

// Basic notification
{
  "topic": "alerts",
  "message": "The task has completed successfully."
}

// Advanced notification
{
  "topic": "alerts",
  "title": "System Alert",
  "message": "CPU usage has exceeded 90% for 5 minutes.",
  "tags": ["warning", "computer"],
  "priority": 4,
  "click": "https://server-dashboard.example.com",
  "actions": [
    {
      "id": "view",
      "label": "View Details",
      "action": "view",
      "url": "https://server-dashboard.example.com/cpu"
    },
    {
      "id": "restart",
      "label": "Restart Service",
      "action": "http",
      "url": "https://api.example.com/restart-service",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer token123"
      }
    }
  ],
  "markdown": true
}

Ejemplo de respuesta:

{
  "success": true,
  "id": "5ZFY362156Sa",
  "topic": "ATLAS",
  "time": 1743064235,
  "expires": 1743496235,
  "message": "This is a test message from the README verification process",
  "title": "README Testing"
}

Recursos

Recursos directos

`ntfy://default`

Descripción: Devuelve el tema ntfy predeterminado configurado en las variables de entorno del servidor ( NTFY_DEFAULT_TOPIC ).
Uso: Útil para que los clientes descubran el tema principal sin necesidad de configuración previa.
Ejemplo: un agente LLM puede acceder a este recurso para utilizar automáticamente el tema predeterminado al enviar notificaciones.
Ejemplo de respuesta:
{ "defaultTopic": "ATLAS", "timestamp": "2025-03-27T08:30:25.619Z", "requestUri": "ntfy://default", "requestId": "0da963d0-30e0-4dbc-bb77-4bf2dee14484" }

Plantillas de recursos

`ntfy://{topic}`

Descripción: Devuelve información sobre un tema ntfy específico.
Parámetros: topic – El nombre del tema ntfy.
Uso: Para consultar información sobre temas distintos a los predeterminados.
Ejemplo de respuesta:
{ "topic": "ATLAS", "timestamp": "2025-03-27T08:30:30.038Z", "requestUri": "ntfy://ATLAS", "requestId": "31baf1df-278f-4fdb-860d-019f156a72b0" }

Casos de uso

Notificaciones de tareas de larga ejecución : reciba notificaciones cuando se completen tareas como copias de seguridad de bases de datos, generación de código o procesamiento de datos.
Recordatorios programados : configure notificaciones retrasadas para futuros eventos o recordatorios.
Sistemas de alerta : configure alertas críticas para monitorear sistemas o eventos importantes.
Notificaciones móviles de LLMs : permita que los LLMs envíen notificaciones directamente a su teléfono.
Actualizaciones de procesos de varios pasos : reciba actualizaciones a medida que se completan las diferentes etapas de un proceso complejo.

Ejemplos de uso

Notificación básica

<use_mcp_tool>
<server_name>ntfy-mcp-server</server_name>
<tool_name>send_ntfy</tool_name>
<arguments>
{
  "topic": "updates",
  "title": "Task Completed",
  "message": "Your requested data analysis has finished",
  "tags": ["check"]
}
</arguments>
</use_mcp_tool>

Notificación enriquecida con acciones

<use_mcp_tool>
<server_name>ntfy-mcp-server</server_name>
<tool_name>send_ntfy</tool_name>
<arguments>
{
  "topic": "alerts",
  "title": "Critical Error Detected",
  "message": "The application has encountered a critical error.\n\n**Error Code**: E123\n\n**Details**: Database connection failed",
  "tags": ["warning", "skull"],
  "priority": 5,
  "actions": [
    {
      "id": "view",
      "label": "View Logs",
      "action": "view",
      "url": "https://logs.example.com"
    },
    {
      "id": "restart",
      "label": "Restart Service",
      "action": "http",
      "url": "https://api.example.com/restart",
      "method": "POST"
    }
  ],
  "markdown": true
}
</arguments>
</use_mcp_tool>

Scripts disponibles

npm run build : compila el código fuente de TypeScript a JavaScript en el directorio dist/ .
npm run clean : elimina el directorio dist/ y limpia el contenido del directorio logs/ .
npm run rebuild : ejecuta clean y luego build .
npm run tree : genera una representación de árbol de directorios en docs/tree.md .
npm start : ejecuta el servidor compilado desde el directorio dist/ usando Node.js.
npm run watch : sigue el archivo de registro combinado ( logs/combined.log ) para monitoreo en tiempo real.

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar solicitudes de incorporación de cambios o abrir problemas para mejorar el proyecto.

Bifurcar el repositorio.
Crea una rama de características ( git checkout -b feature/your-feature ).
Confirme sus cambios ( git commit -m 'Add some feature' ).
Empujar a la rama ( git push origin feature/your-feature ).
Crear una nueva solicitud de extracción.

Para errores y solicitudes de funciones, cree un problema en el repositorio.

Mejores prácticas de desarrollo

Siga las mejores prácticas de TypeScript y mantenga una tipificación sólida
Escribir pruebas para nuevas funcionalidades
Mantenga las dependencias actualizadas
Siga el estilo y los patrones de código existentes

Licencia

Este proyecto está licenciado bajo la licencia Apache-2.0. Consulte el archivo de licencia para más detalles.

Expresiones de gratitud

ntfy.sh para proporcionar el servicio de notificación
Protocolo de contexto de modelo para habilitar conexiones de LLM a herramientas
Todos los colaboradores y usuarios de este proyecto

Integrations

Servidor MCP de Ntfy

Tabla de contenido

Descripción general

Características

Inicio rápido

Instalación

Opción 1: Paquete NPM (recomendado)

Opción 2: Desde la fuente

Configuración

Variables de entorno

Configuración del cliente MCP

Para la extensión Cline VSCode

Si se instala globalmente:

Si se instala desde la fuente:

Para la aplicación de escritorio de Claude

Si se instala globalmente:

Si se instala desde la fuente:

Configuración de Ntfy

Estructura del proyecto

Herramientas

send_ntfy

Argumentos clave:

Ejemplo de uso:

Ejemplo de respuesta:

Recursos

Recursos directos

ntfy://default

Plantillas de recursos

ntfy://{topic}

Casos de uso

Ejemplos de uso

Notificación básica

Notificación enriquecida con acciones

Scripts disponibles

Contribuyendo

Mejores prácticas de desarrollo

Licencia

Expresiones de gratitud

Appeared in Searches

`send_ntfy`

`ntfy://default`

`ntfy://{topic}`