notification

The Notification MCP Server provides a simple way to play bundled notification sounds via the Model Context Protocol. It exposes a tool named play_notification that can be invoked by MCP clients to trigger a system notification sound, optionally displaying a message. By default it ships with a built-in library of sounds (cosmic, fairy, gentle, pleasant, retro, and random) and works cross-platform. To use it, run the MCP server (via npx or your preferred installation method) and then call the play_notification tool from your MCP client, passing an optional message to be shown alongside the sound. You can also configure which sound to play using environment variables, or override the sound with a custom MP3 path if needed.

The server supports 4 main usage modes: use bundled sounds with the default configuration, select a specific bundled sound, choose a random sound on every trigger, or point to your own MP3 file. These settings are controlled through environment variables or per-instance configuration, and the MCP client can request the play_notification tool with a message parameter to display contextual text when a notification plays.

Prerequisites:

• Node.js and npm installed on your machine
• Internet access to fetch the MCP package

Installation steps (recommended):

1. Ensure you have Node.js installed. You can verify with:

node -v
npm -v

2. Install and run the MCP package using NPX (no installation required):

npx @pinkpixel/notification-mcp

3. (Optional) Install globally for easier long-term access:

npm install -g @pinkpixel/notification-mcp
notification-mcp

4. If you prefer to embed this in your project, add the MCP package as a dependency and run/build per your normal workflow. For development, you can build the server locally and run with Node from the build output as described in the project docs.

Configuration examples are provided in the documentation for local development and deployment with your MCP client.

Tips and common considerations:

• By default, MCP uses bundled sounds; set MCP_NOTIFICATION_SOUND to one of: cosmic, fairy, gentle, pleasant, retro, random. Override with MCP_NOTIFICATION_SOUND_PATH to point to your own MP3.
• If using a path to a custom sound, ensure the file is accessible by the runtime and the path is absolute.
• When embedding this in an MCP setup, you can tailor the server invocation by adjusting the mcpServers configuration (command, args, and env variables).
• The Inspector tool (via npm run inspector) can help test and debug the MCP server interactions interactively.
• Ensure your environment has the necessary permissions to access audio playback on the host OS when running on desktop environments.