MCP Notify

What mcp-notify does

The mcp-notify MCP server gives an AI agent a way to alert a person through the computer’s local audio and notification facilities. The primary notify tool plays a sound and displays a system banner. This is useful for long-running tasks, builds, tests, or workflows where the user may not be watching the client continuously.

The agent must provide a title and message for each notification. Titles can contain up to 50 characters, and messages can contain up to 200 characters. The tool also accepts an optional absolute path to an audio or video file with an audio track. Supported examples include MP4, M4A, MP3, WAV, and AIFF files.

list_sounds reports the sounds available to the server and identifies the current default. The package does not use an external API or make network calls for notification delivery.

How it works

The mcp-notify MCP server runs locally as a Node.js process launched through npx. An MCP client calls notify when the agent decides that a task is complete or the user should be alerted. The process then invokes platform-specific local playback and notification facilities.

On macOS, sound playback uses afplay and banners use osascript; both are tested in the project. Linux support tries ffplay, mpg123, paplay, or aplay for sound and uses notify-send for banners on a best-effort basis. Windows uses PowerShell media playback and notification balloon functionality, also on a best-effort basis.

Sound selection follows a fixed order: the NOTIFY_SOUND environment variable, a file beginning with default in the sounds/ directory, the first audio file there alphabetically, a generated chime in assets/, and then a system sound. The bundled sounds/notify-me.mp3 is the default when no earlier choice applies.

Setup and configuration

Install the mcp-notify MCP server by adding its stdio command to the client’s MCP configuration:

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

Claude Desktop uses claude_desktop_config.json; Cursor and VS Code use mcp.json. Node.js 20 or newer is required.

To make an agent call the tool, add an instruction to its AGENTS.md, CLAUDE.md, or system prompt telling it to invoke notify after a task finishes or when the user needs an alert. Set NOTIFY_SOUND to an absolute audio path when a specific sound should take precedence over the normal resolution order.

Tools and capabilities

• notify: Plays a sound and shows a banner using a required title and message, with an optional audio path.
• list_sounds: Lists available sounds and the selected default.
• Local playback and banner delivery across macOS, Linux, and Windows, with platform-specific support levels.
• CI-safe behavior: any CI environment value makes sound and banner playback no-ops.

Limitations and notes

The mcp-notify MCP server depends on local operating-system playback and notification facilities. Linux and Windows behavior is best effort, so the available commands and desktop notification support can affect results. Notifications are limited to the supplied title and message lengths, and the server does not provide remote delivery.

The bundled notify-me.mp3 was generated with ElevenLabs under a commercial license. The project itself is licensed under MIT. Local development commands include type checking and an end-to-end test that triggers sound and banner output, so tests may produce local notifications unless CI is set.