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