mcp-notifications

官方

桌面系统通知，用于MCP代理——即时反馈任务、故障及工作流事件。

GitHub
2

你可以用 Notifications MCP 做什么？

  • 发送桌面通知 — 当任务完成时，要求代理调用 send_notification 并附带自定义标题和消息。
  • 包含声音提醒 — 设置 play_sound: true，使通知在送达时播放系统声音。
  • 在Windows上自定义通知来源 — 传递 app_id 以控制toast中显示的应用程序名称，或通过 MCP_NOTIFICATIONS_APP_ID 环境变量全局设置。
  • 使用自定义图标 — 提供 icon 路径以替换通知中的默认图像。

文档

mcp-notifications

npm version

🚀 更快交付。不错过任何消息。

mcp-notifications 让你的 MCP 代理能够为已完成的任务、失败和重要更新发送桌面通知。

这对控制台 AI 代理尤其有用，因为它们通常默认没有内置通知。

无需每分钟都去查看聊天。
不再有沉默的代理响应。
只有桌面上可见、可靠的反馈。🔔

它解决的常见问题

你给多个 AI 代理分配任务，然后等待并不断检查谁已经回复。

使用 mcp-notifications，这就简单多了：代理可以在需要你输入或工作完成时，在桌面上通知你。

团队安装它的原因

  • ⚡ 来自 MCP 工作流的即时反馈。
  • 🧠 更好的专注度：让代理工作，你继续处理主要任务。
  • 🖥️ 通过 node-notifier 的原生操作系统通知。
  • 🧵 非阻塞行为：通知发送在后台排队。

全局安装

要求：

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

可执行文件名称（在 MCP 配置中使用）：

mcp-notifications

mcp-notifications 是一个 MCP 服务器入口点（stdio），而不是一次性通知命令。

设置：Codex

将其添加到 ~/.codex/config.toml：

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

配置更新后重启 Codex。

设置：Claude Agent

将 MCP 服务器配置添加到你的 Claude 客户端配置文件：

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

然后重启 Claude 客户端。

AI 代理通知指令

通知有两种方式：手动和自动。

选择更适合你工作流程的方式。

手动

在你想被通知的任务中，明确要求代理。示例：

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

你还可以在特定聊天中定义声音、主题和频率规则。示例：

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

自动

自动通知可以全局配置或按项目配置。

启用代理回复自动通知的示例指令：

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

时间是一个粗略的阈值，取决于模型行为，因此请根据自己的偏好调整此指令。

在技能中

你还可以在特定技能中启用通知。以 Review 技能为例：

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

工具

send_notification

输入：

  • title string（必需）
  • message string（必需）
  • play_sound boolean（可选，默认：false）
  • icon string（可选，图像文件的绝对或相对路径）
  • app_id string（可选，用于 Toast 来源的 Windows 应用用户模型 ID）

示例：

{
  "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 控制 Windows Toast 通知中显示的来源。
  • 如果未设置 app_id，Windows 可能会将 SnoreToast 显示为来源。
  • 你可以在每次工具调用中传递 app_id，或者将 MCP_NOTIFICATIONS_APP_ID 设置为服务器的环境变量。

后端选择

你可以通过环境变量 MCP_NOTIFICATIONS_BACKEND 选择通知传输方式：

  • auto（默认）：如果可用，在 WSL 中使用 powershell，否则使用 node-notifier
  • powershell：强制使用 powershell.exe Windows Toast 传输（推荐用于 WSL）
  • node-notifier：强制使用 node-notifier 包

在 Codex 中测试的聊天提示

直接在聊天中使用这些消息：

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

日志/响应中预期的工具结果：

Notification queued

行为

  • ✅ 使用标准系统通知渠道。
  • 🔊 当 play_sound: true 时，使用标准系统通知声音。
  • 🤖 使用捆绑的 Topvisor 机器人图像作为默认通知图标。
  • 🧰 快速返回，同时通知在后台队列中传递。

示例

AI 代理正在等你：

example.png