JinDaGe - macos-notify-mcp MCP Details

article

README

🚀 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

macos-notify-mcp