Macos Notify MCP

🚀 macOS Notify MCP

このツールは、tmuxと統合されたmacOS通知用のモデルコンテキストプロトコル（MCP）サーバーです。ClaudeなどのAIアシスタントが、クリックすると特定のtmuxセッションにフォーカスを移すことができるネイティブなmacOS通知を送信できるようになります。

✨ 主な機能

• 🔔 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. 複数インスタンス: 各通知は別々のプロセスとして実行され、複数の同時通知を可能にします。

アーキテクチャ

このプロジェクトは、2つの主要なコンポーネントで構成されています。

1. MCP Server/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