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-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 Ajuste las variables

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