mcp-notifications

oficial

Notificações do sistema desktop para agentes MCP — feedback instantâneo sobre tarefas, falhas e eventos de fluxo de trabalho.

GitHub
2

O que você pode fazer com Notifications MCP?

  • Send a desktop notification — Ask the agent to call send_notification with a custom title and message when a task finishes.
  • Include an audible alert — Set play_sound: true so the notification plays the system sound on delivery.
  • Customize the notification source on Windows — Pass an app_id to control the app name shown in the toast, or set it globally via the MCP_NOTIFICATIONS_APP_ID environment variable.
  • Use a custom icon — Provide an icon path to replace the default image in the notification.

Documentação

mcp-notifications

npm version

🚀 Entregue mais rápido. Não perca nada.

mcp-notifications permite que seu agente MCP envie notificações na área de trabalho para tarefas concluídas, falhas e atualizações importantes.

Isso é especialmente útil para agentes de IA de console, porque eles geralmente não possuem notificações integradas por padrão.

Chega de verificar conversas a cada minuto.
Chega de respostas silenciosas do agente.
Apenas feedback visível e confiável na sua área de trabalho. 🔔

Problema comum que isso resolve

Você atribui tarefas a vários agentes de IA, depois espera e fica verificando quem já respondeu.

Com mcp-notifications, isso fica mais simples: o agente pode notificá-lo na área de trabalho quando precisar da sua contribuição ou quando o trabalho estiver concluído.

Por que as equipes instalam isso

  • ⚡ Feedback imediato dos seus fluxos de trabalho MCP.
  • 🧠 Melhor foco: deixe o agente trabalhar enquanto você permanece na sua tarefa principal.
  • 🖥️ Notificações nativas do SO via node-notifier.
  • 🧵 Comportamento não bloqueante: o envio de notificações é enfileirado em segundo plano.

Instalar globalmente

Requisitos:

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

Nome do executável (use isso na configuração MCP):

mcp-notifications

mcp-notifications é um ponto de entrada do servidor MCP (stdio), não um comando de notificação única.

Configuração: Codex

Adicione isso ao ~/.codex/config.toml:

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

Reinicie o Codex após a atualização da configuração.

Configuração: Claude Agent

Adicione a configuração do servidor MCP ao seu arquivo de configuração do cliente Claude:

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

Em seguida, reinicie o cliente Claude.

Instruções de Notificação do Agente de IA

Existem duas abordagens para notificações: manual e automática.

Escolha a que funciona melhor para o seu fluxo de trabalho.

Manual

Em uma tarefa onde você deseja ser notificado, peça explicitamente ao agente. Exemplo:

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

Você também pode definir regras de som, tópico e frequência dentro de um chat específico. Exemplo:

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

Automática

Notificações automáticas podem ser configuradas globalmente ou por projeto.

Exemplo de instrução para habilitar notificações automáticas para respostas do 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}'`

O tempo é um limite aproximado e depende do comportamento do modelo, então ajuste esta instrução de acordo com suas preferências.

Em Skills

Você também pode habilitar notificações em skills específicas. Exemplo para uma skill de Revisão:

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

Ferramenta

send_notification

Entrada:

  • title string (obrigatório)
  • message string (obrigatório)
  • play_sound boolean (opcional, padrão: false)
  • icon string (opcional, caminho absoluto ou relativo para arquivo de imagem)
  • app_id string (opcional, ID do Modelo de Usuário do Aplicativo Windows para origem do toast)

Exemplo:

{
  "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 a origem exibida nas notificações toast do Windows.
  • Se app_id não estiver definido, o Windows pode mostrar SnoreToast como a origem.
  • Você pode passar app_id em cada chamada de ferramenta ou definir MCP_NOTIFICATIONS_APP_ID como uma variável de ambiente para o servidor.

Seleção de backend

Você pode selecionar o transporte de notificação via env MCP_NOTIFICATIONS_BACKEND:

  • auto (padrão): usa powershell no WSL se disponível, caso contrário node-notifier
  • powershell: força o transporte de toast do Windows powershell.exe (recomendado para WSL)
  • node-notifier: força o pacote node-notifier

Prompts de Chat para Testar no Codex

Use estas mensagens diretamente no 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 da ferramenta nos logs/resposta:

Notification queued

Comportamento

  • ✅ Usa canais de notificação padrão do sistema.
  • 🔊 Usa o som de notificação padrão do sistema quando play_sound: true.
  • 🤖 Usa a imagem do robô Topvisor empacotada como ícone de notificação padrão.
  • 🧰 Retorna rapidamente enquanto as notificações são entregues na fila em segundo plano.

Exemplo

O agente de IA está esperando por você:

example.png