Mcp Notify

io.github.mrfqcenticPublished by GitHub account mrfqcenticv0.2.1Updated Oct 25, 2026

Minimal MCP server that plays a sound and shows a system banner when an AI agent finishes a task

VerifiedSTDIODesktop onlyProductivity & Workflow

Overview

AI-generated overview

A minimal local MCP server that plays a notification sound and shows a system banner when an AI agent finishes a task or needs attention.

What you can do
Play a sound and show a desktop banner with a short title and message supplied by the agent, optionally using a chosen audio file path as the sound alert. List the available sounds and the currently selected default. Sound selection follows a fixed order: an environment variable path, a pinned default file, the first audio file in the sounds folder, a generated chime, then the system sound.
When to use it
Useful when you run long agent tasks and want an audible and visual alert on your own machine when the agent finishes or needs your input, rather than watching the session. Works with MCP clients such as Claude Desktop, Cursor, VS Code and others.
Requirements
Runs locally over stdio via npx, so Node.js 20 or newer is needed. No API keys, accounts or network calls. Sound and banner rely on local OS facilities: afplay and osascript on macOS, a fallback chain of ffplay, mpg123, paplay or aplay and notify-send on Linux, PowerShell on Windows. An optional NOTIFY_SOUND environment variable sets the sound file path.
Before you install
The agent must be told to call the notify tool, for example through a line in your agent instructions file. Sound and banner support is tested on macOS and best effort on Linux and Windows. Any CI environment value silently disables sound and banner playback. The tool only touches local audio and notification facilities.

Installation

In SourceWeft

  1. Open Mcp Notify in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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):

json
{  "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).

ParamRequiredDescription
titleyesShort banner title, e.g. "Build finished"
messageyes1–2 sentence description, e.g. "All 142 tests passed"
soundnoAbsolute 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.

json
{  "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

OSSoundBanner
macOSafplay (tested)osascript (tested)
Linuxffplay / mpg123 / paplay / aplay fallback chain (best effort)notify-send (best effort)
WindowsPowerShell 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

sh
npm installnpm run typechecknpm test          # builds, then runs the e2e suite (sound + banner fire locally)

License

MIT — see LICENSE.

Source: README.md at commit 926225e

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts