Macos Notify MCP

🚀 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

支持的终端检测

该工具使用多种方法检测终端：

1. Cursor：通过 CURSOR_TRACE_ID 环境变量
2. VSCode：通过 VSCODE_IPC_HOOK_CLI 或 VSCODE_REMOTE 环境变量
3. alacritty：通过 ALACRITTY_WINDOW_ID 或 ALACRITTY_SOCKET 环境变量
4. iTerm2：通过 TERM_PROGRAM=iTerm.app
5. Terminal.app：通过 TERM_PROGRAM=Apple_Terminal

tmux 中的终端检测

当在 tmux 中运行时，该工具会尝试检测活动 tmux 客户端使用的终端模拟器：

1. 活动客户端检测：识别最近活动的 tmux 客户端
2. TTY 进程分析：跟踪使用客户端 TTY 的进程
3. 环境变量保留：检查保留的环境变量
4. 进程树回退：作为最后手段分析进程树

有关高级 tmux 客户端跟踪的详细信息，请参阅 examples/tmux-client-tracking.sh。

🔧 技术细节

工作原理

1. 通知发送：使用原生 macOS 应用程序包（MacOSNotifyMCP.app）通过 UserNotifications API 发送通知
2. 点击处理：当点击通知时，应用程序会激活检测到的终端模拟器（VSCode、Cursor、iTerm2、alacritty 或 Terminal.app）并切换到指定的 tmux 会话
3. 终端支持：自动检测并激活正确的终端应用程序
4. 多实例支持：每个通知作为一个单独的进程运行，支持多个并发通知

架构

该项目由两个主要组件组成：

1. MCP 服务器/CLI（TypeScript/Node.js）

   • 实现模型上下文协议
   • 提供命令行界面
   • 管理 tmux 会话的检测和验证

2. MacOSNotifyMCP.app（Swift/macOS）

   • 用于通知的原生 macOS 应用程序
   • 处理通知点击以聚焦到 tmux 会话
   • 每个通知作为后台进程运行

MacOSNotifyMCP.app

MacOSNotifyMCP.app 已包含在 npm 包中，安装后即可自动使用，无需额外设置。

📚 详细文档

故障排除

通知未显示

1. 检查系统设置 → 通知 → MacOSNotifyMCP
2. 确保允许通知
3. 运行 macos-notify-mcp -m "test" 进行验证

tmux 集成不起作用

1. 确保已安装并运行 tmux
2. 使用 macos-notify-mcp --list-sessions 检查会话名称
3. 验证终端应用程序是否受支持（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