🚀 macOS Notify MCP
这是一个适用于 macOS 通知的模型上下文协议（MCP）服务器，支持与 tmux 集成。该工具允许像 Claude 这样的 AI 助手发送原生 macOS 通知，点击通知时可以聚焦到特定的 tmux 会话。
✨ 主要特性
- 🔔 使用 UserNotifications API 发送原生 macOS 通知
- 🖱️ 可点击的通知，点击后能聚焦到 tmux 会话
- 🎯 直接导航到特定的 tmux 会话、窗口和窗格
- 🔊 可自定义通知声音
- 🚀 支持多个并发通知
- 🤖 用于 AI 助手集成的 MCP 服务器
- 🖥️ 支持检测终端模拟器（VSCode、Cursor、iTerm2、Terminal.app）
📦 安装指南
前提条件
- macOS（通知功能必需）
- Node.js >= 18.0.0
- tmux（可选，用于 tmux 集成）
从 npm 安装
npm install -g macos-notify-mcp
从源代码构建
git clone https://github.com/yuki-yano/macos-notify-mcp.git
cd macos-notify-mcp
npm install
npm run build
npm run build-app # 构建 macOS 应用程序包（仅开发时需要）
💻 使用示例
作为 MCP 服务器
首先，全局安装该包：
npm install -g macos-notify-mcp
使用 Claude Code 快速设置
使用 claude mcp add 命令：
claude mcp add macos-notify -s user -- macos-notify-mcp
然后重启 Claude Code。
Claude Desktop 手动设置
编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：
{
"mcpServers": {
"macos-notify": {
"command": "macos-notify-mcp"
}
}
}
可用的 MCP 工具
-
send_notification- 发送 macOS 通知message（必需）：通知消息title：通知标题（默认："Claude Code"）sound：通知声音（默认："Glass"）session：tmux 会话名称window：tmux 窗口编号pane：tmux 窗格编号useCurrent：使用当前 tmux 位置
-
list_tmux_sessions- 列出可用的 tmux 会话 -
get_current_tmux_info- 获取当前 tmux 会话信息
作为 CLI 工具
# 基本通知
macos-notify-cli -m "Build completed"
# 带标题的通知
macos-notify-cli -t "Development" -m "Tests passed"
# 与 tmux 集成的通知
macos-notify-cli -m "Task finished" -s my-session -w 1 -p 0
# 使用当前 tmux 位置
macos-notify-cli -m "Check this pane" --current-tmux
# 检测当前终端模拟器
macos-notify-cli --detect-terminal
# 列出 tmux 会话
macos-notify-cli --list-sessions
终端检测
该工具会自动检测你使用的终端模拟器，并在你点击通知时利用此信息聚焦到正确的应用程序。你可以使用以下命令测试终端检测：
# 测试终端检测
macos-notify-cli --detect-terminal
支持的终端检测
该工具使用多种方法检测终端：
- Cursor：通过
CURSOR_TRACE_ID环境变量 - VSCode：通过
VSCODE_IPC_HOOK_CLI或VSCODE_REMOTE环境变量 - alacritty：通过
ALACRITTY_WINDOW_ID或ALACRITTY_SOCKET环境变量 - iTerm2：通过
TERM_PROGRAM=iTerm.app - Terminal.app：通过
TERM_PROGRAM=Apple_Terminal
tmux 中的终端检测
当在 tmux 中运行时，该工具会尝试检测活动 tmux 客户端使用的终端模拟器：
- 活动客户端检测：识别最近活动的 tmux 客户端
- TTY 进程分析：跟踪使用客户端 TTY 的进程
- 环境变量保留：检查保留的环境变量
- 进程树回退：作为最后手段分析进程树
有关高级 tmux 客户端跟踪的详细信息，请参阅 examples/tmux-client-tracking.sh。
🔧 技术细节
工作原理
- 通知发送：使用原生 macOS 应用程序包（MacOSNotifyMCP.app）通过 UserNotifications API 发送通知
- 点击处理：当点击通知时，应用程序会激活检测到的终端模拟器（VSCode、Cursor、iTerm2、alacritty 或 Terminal.app）并切换到指定的 tmux 会话
- 终端支持：自动检测并激活正确的终端应用程序
- 多实例支持：每个通知作为一个单独的进程运行，支持多个并发通知
架构
该项目由两个主要组件组成：
-
MCP 服务器/CLI（TypeScript/Node.js）
- 实现模型上下文协议
- 提供命令行界面
- 管理 tmux 会话的检测和验证
-
MacOSNotifyMCP.app（Swift/macOS）
- 用于通知的原生 macOS 应用程序
- 处理通知点击以聚焦到 tmux 会话
- 每个通知作为后台进程运行
MacOSNotifyMCP.app
MacOSNotifyMCP.app 已包含在 npm 包中，安装后即可自动使用，无需额外设置。
📚 详细文档
故障排除
通知未显示
- 检查系统设置 → 通知 → MacOSNotifyMCP
- 确保允许通知
- 运行
macos-notify-mcp -m "test"进行验证
tmux 集成不起作用
- 确保已安装并运行 tmux
- 使用
macos-notify-mcp --list-sessions检查会话名称 - 验证终端应用程序是否受支持（Alacritty、iTerm2、WezTerm 或 Terminal）
开发
# 安装依赖
npm install
# 构建 TypeScript
npm run build
# 开发模式运行
npm run dev
# 代码检查和格式化
npm run lint
npm run format
# 构建 macOS 应用程序（仅在修改 Swift 代码时需要）
npm run build-app
📄 许可证
MIT
作者
Yuki Yano