mcp-notify

Minimal MCP server that plays a notification sound and shows a system banner on your computer whenever your AI agent finishes a task or needs your attention.

Works with any MCP client: Claude Desktop, Claude Code, Cursor, VS Code, opencode, Cline, and more. One 3-line config, no API keys, no network calls — it only touches your local audio and notification facilities.

Install

Add to your client's MCP config (Claude Desktop claude_desktop_config.json, Cursor / VS Code mcp.json, or opencode config):

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

(opencode users: same shape under the mcp key with "type": "local" and "command": ["npx", "-y", "@mrfqcentic/mcp-notify"].)

Requires Node.js >= 20.

Make the agent call it

Add one line to your AGENTS.md / CLAUDE.md / system prompt:

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.

Tools

notify

Plays the sound and shows a banner. The agent always supplies title (max 50 chars) and message (max 200 chars).

| Param | Required | Description | |---|---|---| | title | yes | Short banner title, e.g. "Build finished" | | message | yes | 1–2 sentence description, e.g. "All 142 tests passed" | | sound | no | Absolute path to any audio/video file with audio (mp4, m4a, mp3, wav, aiff) |

list_sounds

Lists available sounds and the currently selected default.

Choosing your sound

Resolution order:

1. NOTIFY_SOUND env var — absolute path, explicit and deterministic
2. A file in the sounds/ folder whose name starts with default (your pin)
3. First audio file in the sounds/ folder (alphabetical — notify-me.mp3 ships here as the bundled default)
4. The generated chime in assets/
5. The system sound (macOS Glass.aiff, Linux bell.oga)

Tip: rename or copy your favorite sound to sounds/default.mp3 (or set NOTIFY_SOUND) to make it stick.

The bundled sounds/notify-me.mp3 was generated with ElevenLabs under a commercial license.

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

Tip: MP4 files with an audio track work too (macOS afplay reads the audio stream).

Platforms

| OS | Sound | Banner | |---|---|---| | macOS | afplay (tested) | osascript (tested) | | Linux | ffplay / mpg123 / paplay / aplay fallback chain (best effort) | notify-send (best effort) | | Windows | PowerShell MediaPlayer (best effort) | PowerShell NotifyIcon balloon (best effort) |

Any CI env value makes sound and banner playback no-ops (set automatically in CI workflows) so the test suite can run on machines without audio.

Development

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

License

MIT — see LICENSE.