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

Related MCP server: ntfy-me-mcp

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

1. Prerrequisitos:

   • Node.js (v16+)

   • npm o hilo

   • Un cliente compatible con MCP (Claude Desktop, Cline, etc.)

2. 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

3. Agregar a la configuración del cliente MCP: agregue el servidor a su archivo de configuración del cliente MCP (consulte Configuración )

4. Usar la herramienta: Una vez conectado, puedes usar la herramienta send_ntfy para enviar notificaciones.

Instalación

Opción 1: Paquete NPM (recomendado)

1. 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.

2. 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

1. Clonar el repositorio:

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

2. Instalar dependencias:

   npm install

3. 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

1. Instale la aplicación ntfy en sus dispositivos desde ntfy.sh o las tiendas de aplicaciones

2. Suscríbete a tu tema en la aplicación

3. 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:

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

1. 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.

2. Recordatorios programados : configure notificaciones retrasadas para futuros eventos o recordatorios.

3. Sistemas de alerta : configure alertas críticas para monitorear sistemas o eventos importantes.

4. Notificaciones móviles de LLMs : permita que los LLMs envíen notificaciones directamente a su teléfono.

5. 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.

1. Bifurcar el repositorio.

2. Crea una rama de características ( git checkout -b feature/your-feature ).

3. Confirme sus cambios ( git commit -m 'Add some feature' ).

4. Empujar a la rama ( git push origin feature/your-feature ).

5. 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