mcp-notifications

oficial

Notificaciones del sistema de escritorio para agentes MCP: retroalimentación instantánea sobre tareas, fallos y eventos del flujo de trabajo.

GitHub
2

¿Qué puedes hacer con Notifications MCP?

  • Enviar una notificación de escritorio — Pídele al agente que llame a send_notification con un título y mensaje personalizados cuando una tarea finalice.
  • Incluir una alerta audible — Establece play_sound: true para que la notificación reproduzca el sonido del sistema al entregarse.
  • Personalizar la fuente de la notificación en Windows — Pasa un app_id para controlar el nombre de la aplicación que se muestra en el toast, o configúralo globalmente mediante la variable de entorno MCP_NOTIFICATIONS_APP_ID.
  • Usar un icono personalizado — Proporciona una ruta de icon para reemplazar la imagen predeterminada en la notificación.

Documentación

mcp-notifications

npm version

🚀 Envía más rápido. No te pierdas nada.

mcp-notifications permite que tu agente MCP envíe notificaciones de escritorio para tareas completadas, fallos y actualizaciones importantes.

Esto es especialmente útil para agentes de IA en consola, porque normalmente no tienen notificaciones integradas por defecto.

No más revisar chats cada minuto.
No más respuestas silenciosas del agente.
Solo retroalimentación visible y confiable en tu escritorio. 🔔

Problema común que resuelve

Das tareas a varios agentes de IA, luego esperas y revisas constantemente quién ya respondió.

Con mcp-notifications, esto se simplifica: el agente puede notificarte en el escritorio cuando necesite tu opinión o cuando el trabajo esté terminado.

Por qué los equipos lo instalan

  • ⚡ Retroalimentación inmediata de tus flujos de trabajo MCP.
  • 🧠 Mejor concentración: deja que el agente trabaje mientras tú sigues con tu tarea principal.
  • 🖥️ Notificaciones nativas del sistema operativo a través de node-notifier.
  • 🧵 Comportamiento no bloqueante: el envío de notificaciones se encola en segundo plano.

Instalación global

Requisitos:

  • Node.js >=20
  • npm >=10
npm i -g @topvisor/mcp-notifications

Nombre del ejecutable (úsalo en la configuración MCP):

mcp-notifications

mcp-notifications es un punto de entrada del servidor MCP (stdio), no un comando de notificación de un solo uso.

Configuración: Codex

Agrega esto a ~/.codex/config.toml:

[mcp_servers.notifications]
enabled = true
command = "mcp-notifications"
args = []

Reinicia Codex después de actualizar la configuración.

Configuración: Claude Agent

Agrega la configuración del servidor MCP a tu archivo de configuración del cliente Claude:

{
  "mcpServers": {
    "notifications": {
      "command": "mcp-notifications",
      "args": []
    }
  }
}

Luego reinicia el cliente Claude.

Instrucciones de notificación para el agente de IA

Hay dos enfoques para las notificaciones: manual y automático.

Elige el que funcione mejor para tu flujo de trabajo.

Manual

En una tarea donde quieras ser notificado, pídeselo explícitamente al agente. Ejemplo:

Count files in the project; after the task is fully complete, notify me with sound.

También puedes definir reglas de sonido, tema y frecuencia dentro de un chat específico. Ejemplo:

Notify me about your replies without sound, include the reply text, and use title: "Large Refactoring"

Automático

Las notificaciones automáticas se pueden configurar globalmente o por proyecto.

Instrucción de ejemplo para habilitar notificaciones automáticas en las respuestas del agente:

Send `send_notification` after your replies (actual task time >5 seconds or many steps); `play_sound: false`; `app_id: '{put your chat name here}'`

El tiempo es un umbral aproximado y depende del comportamiento del modelo, así que ajusta esta instrucción según tus preferencias.

En Skills

También puedes habilitar notificaciones en skills específicas. Ejemplo para una skill de Revisión:

After the review, run `send_notification` with a short summary; `play_sound: true`; `app_id: 'Reviewer {put task id here}'`

Herramienta

send_notification

Entrada:

  • title string (requerido)
  • message string (requerido)
  • play_sound boolean (opcional, predeterminado: false)
  • icon string (opcional, ruta absoluta o relativa al archivo de imagen)
  • app_id string (opcional, ID del modelo de usuario de la aplicación de Windows para el origen de la notificación)

Ejemplo:

{
  "title": "Codex",
  "message": "Deployment completed successfully",
  "play_sound": true,
  "icon": "/opt/mcp-notifications/icons/custom.png",
  "app_id": "Topvisor.Codex"
}

app_id (Windows)

  • app_id controla el origen que se muestra en las notificaciones de Windows.
  • Si app_id no está configurado, Windows puede mostrar SnoreToast como origen.
  • Puedes pasar app_id en cada llamada a la herramienta, o establecer MCP_NOTIFICATIONS_APP_ID como variable de entorno para el servidor.

Selección de backend

Puedes seleccionar el transporte de notificaciones mediante la variable de entorno MCP_NOTIFICATIONS_BACKEND:

  • auto (predeterminado): usa powershell en WSL si está disponible, de lo contrario node-notifier
  • powershell: fuerza el transporte de notificaciones de Windows powershell.exe (recomendado para WSL)
  • node-notifier: fuerza el paquete node-notifier

Mensajes de chat para probar en Codex

Usa estos mensajes directamente en el chat:

Check send_notification

Send a notification without sound: title "Test", message "Check"

Send a notification with sound: title "Test", message "Check"

Send a notification with app_id "Topvisor.Codex": title "Test", message "Check"

Send 3 test notifications in a row without sound

Resultado esperado de la herramienta en registros/respuesta:

Notification queued

Comportamiento

  • ✅ Utiliza los canales de notificación estándar del sistema.
  • 🔊 Usa el sonido de notificación estándar del sistema cuando play_sound: true.
  • 🤖 Utiliza la imagen del robot Topvisor incluida como icono de notificación predeterminado.
  • 🧰 Retorna rápidamente mientras las notificaciones se entregan en una cola en segundo plano.

Ejemplo

El agente de IA te está esperando:

example.png