mcp-notifications

mcp-notifications

🚀 更快交付，不错过任何事。

mcp-notifications 可让你的 MCP Agent 发送桌面通知，告知任务已完成、发生失败或有重要更新。

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

不用再每分钟查看聊天。
不再错过 Agent 的静默回复。
在桌面上获得清晰、可靠的反馈。🔔

本工具解决的常见问题

你把任务交给多个 AI Agent，然后等待并不断查看谁已经回复。

使用 mcp-notifications 后，事情会简单一些：Agent 需要你提供信息或完成工作时，可以向你的桌面发送通知。

团队安装它的理由

• ⚡ MCP 工作流的即时反馈。
• 🧠 更专注：让 Agent 工作，而你继续处理手头的主要任务。
• 🖥️ 通过 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 Agent 通知说明

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

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

手动

在希望收到通知的任务中，明确告知 Agent。示例：

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"

自动

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

启用 Agent 回复自动通知的说明示例：

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 Agent 正在等待你：