mcp-notify

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.