mcp-notify

mcp-notify

轻量级 MCP 服务：每当 AI Agent 完成任务或需要你关注时，会在电脑上播放通知音效并显示系统横幅。

适用于任何 MCP 客户端：Claude Desktop、Claude Code、Cursor、VS Code、opencode、Cline 等。只需 3 行配置，无需 API 密钥，也不会发起网络请求——它只会使用本地音频和通知功能。

安装

将以下内容添加到客户端的 MCP 配置中（Claude Desktop 的 claude_desktop_config.json、Cursor / VS Code 的 mcp.json，或 opencode 配置）：

{
  "mcpServers": {
    "mcp-notify": {
      "command": "npx",
      "args": ["-y", "@mrfqcentic/mcp-notify"]
    }
  }
}

（opencode 用户：在 mcp 键下使用相同结构，并设置 "type": "local" 和 "command": ["npx", "-y", "@mrfqcentic/mcp-notify"]。）

需要 Node.js >= 20。

让 Agent 调用它

在 AGENTS.md / CLAUDE.md / 系统提示词中添加一行：

When a task is done or the user should be alerted, call the `notify` tool with a short title and a 1–2 sentence description of the result.

工具

notify

播放音效并显示横幅。Agent 始终会提供 title（最多 50 个字符）和 message（最多 200 个字符）。

参数	必填	描述
title	是	简短的横幅标题，例如“构建已完成”
message	是	1–2 句描述，例如“142 项测试全部通过”
sound	否	任意音频或视频文件的绝对路径（mp4、m4a、mp3、wav、aiff）

list_sounds

列出可用音效和当前选定的默认音效。

选择音效

查找顺序：

1. NOTIFY_SOUND 环境变量——绝对路径，明确且确定
2. sounds/ 文件夹中名称以 default 开头的文件（固定使用的音效）
3. sounds/ 文件夹中的第一个音频文件（按字母顺序——此处附带的默认音效为 notify-me.mp3）
4. assets/ 中生成的提示音
5. 系统音效（macOS Glass.aiff、Linux bell.oga）

提示：将喜欢的音效重命名或复制为 sounds/default.mp3（或设置 NOTIFY_SOUND），即可固定使用。

随附的 sounds/notify-me.mp3 由 ElevenLabs 在商业许可下生成。

{
  "mcpServers": {
    "mcp-notify": {
      "command": "npx",
      "args": ["-y", "@mrfqcentic/mcp-notify"],
      "env": { "NOTIFY_SOUND": "/absolute/path/to/your-sound.mp3" }
    }
  }
}

提示：带有音轨的 MP4 文件也可使用（macOS afplay 可以读取音频流）。

平台

操作系统	音效	横幅
macOS	afplay（已测试）	osascript（已测试）
Linux	ffplay / mpg123 / paplay / aplay 回退链（尽力而为）	notify-send（尽力而为）
Windows	PowerShell MediaPlayer（尽力而为）	PowerShell NotifyIcon 气泡通知（尽力而为）

任何 CI 环境变量值都会使音效和横幅播放操作变为无操作（CI 工作流中会自动设置），因此测试套件可以在没有音频设备的机器上运行。

开发

npm install
npm run typecheck
npm test          # builds, then runs the e2e suite (sound + banner fire locally)

许可证

MIT——请参阅 LICENSE。