# mcp-notify [Health: Active]

**Category:** 🖥️ OS Automation  
**Repository:** https://github.com/mrfqcentic/mcp-notify  
**GitHub Stars:** 0  
**npm Downloads (last month):** 131  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-notify

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

## Tools
Capabilities this server exposes over MCP:

- **notify** — Plays the sound and shows a banner. The agent always supplies `title` (max 50 chars) and `message` (max 200 chars).
- **list_sounds** — Lists available sounds and the currently selected default.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

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

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

_Full upstream README: https://allmcps.com/mcp/mcp-notify/readme_