mcp-notify

mcp-notify

AI エージェントがタスクを完了したときや、注意が必要なときに、コンピューターで通知音を鳴らし、システムバナーを表示する最小限の MCP サーバーです。

Claude Desktop、Claude Code、Cursor、VS Code、opencode、Cline など、あらゆる MCP クライアントで動作します。設定は 3 行だけで、API キーもネットワーク通信も不要です。ローカルの音声機能と通知機能のみを使用します。

インストール

クライアントの MCP 設定に追加します（Claude Desktop の claude_desktop_config.json、Cursor / VS Code の mcp.json、または opencode の設定）：

{
  "mcpServers": {
    "mcp-notify": {
      "command": "npx",
      "args": ["-y", "@mrfqcentic/mcp-notify"]
    }
  }
}

（opencode のユーザーは、mcp キーの下に同じ形式で "type": "local" と "command": ["npx", "-y", "@mrfqcentic/mcp-notify"] を指定してください。）

Node.js >= 20 が必要です。

エージェントから呼び出す

AGENTS.md / CLAUDE.md / システムプロンプトに 1 行追加します：

When a task is done or the user should be alerted, call the `notify` tool with a short title and a 1–2 sentence description of the result.

ツール

notify

音を鳴らし、バナーを表示します。エージェントは必ず title（最大 50 文字）と message（最大 200 文字）を指定します。

パラメーター	必須	説明
title	はい	バナーの短いタイトル。例：「ビルドが完了しました」
message	はい	1～2 文の説明。例：「142 件のテストがすべて成功しました」
sound	いいえ	音声を含む音声／動画ファイル（mp4、m4a、mp3、wav、aiff）の絶対パス

list_sounds

利用可能なサウンドと、現在選択されているデフォルトを一覧表示します。

サウンドの選択

解決順序：

1. NOTIFY_SOUND 環境変数 — 明示的で決定性のある絶対パス
2. sounds/ フォルダー内で名前が default で始まるファイル（指定したサウンド）
3. sounds/ フォルダー内の最初の音声ファイル（アルファベット順 — バンドルされたデフォルトとして notify-me.mp3 が含まれています）
4. assets/ 内で生成されたチャイム音
5. システムサウンド（macOS の Glass.aiff、Linux の bell.oga）

ヒント：お気に入りのサウンドを sounds/default.mp3 に名前変更するかコピーする（または NOTIFY_SOUND を設定する）と、固定できます。

バンドルされている sounds/notify-me.mp3 は、商用ライセンスのもとで ElevenLabs を使用して生成されました。

{
  "mcpServers": {
    "mcp-notify": {
      "command": "npx",
      "args": ["-y", "@mrfqcentic/mcp-notify"],
      "env": { "NOTIFY_SOUND": "/absolute/path/to/your-sound.mp3" }
    }
  }
}

ヒント：音声トラックを含む MP4 ファイルも使用できます（macOS の afplay は音声ストリームを再生します）。

プラットフォーム

OS	サウンド	バナー
macOS	afplay（テスト済み）	osascript（テスト済み）
Linux	ffplay / mpg123 / paplay / aplay のフォールバックチェーン（ベストエフォート）	notify-send（ベストエフォート）
Windows	PowerShell の MediaPlayer（ベストエフォート）	PowerShell の NotifyIcon バルーン（ベストエフォート）

CI 環境変数に値が設定されている場合（CI ワークフローでは自動設定）、音声とバナーの再生は何も行いません。そのため、音声機能のないマシンでもテストスイートを実行できます。

開発

npm install
npm run typecheck
npm test          # builds, then runs the e2e suite (sound + banner fire locally)

ライセンス

MIT — LICENSE を参照してください。