Notifications

You can run a lightweight, configurable notification MCP server that plays bundled or custom sounds when tasks complete. It’s designed to be easy to run with npx, so you can add audible task feedback to your automation without manual sound management.

How to use

Set up your MCP client to call the play_notification tool whenever a task finishes. You can customize which sound is played by choosing a bundled option, selecting a custom MP3 file, or letting the server pick a random sound each time.

How to install

Prerequisites you need before installing and running the server are Node.js and npm. You can install Node.js from the official site, which also provides npm. Once Node.js is installed, you have what you need to start.

Additional setup guidance

Choose how you want to run the MCP server. The following options show how to configure the server so your client can request a notification sound on task completion. All options use the same base tool, with environment variables controlling which sound to play.

Configuration examples

"````json
{
  "mcpServers": {
    "notifications": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/notification-mcp"]
    }
  }
}

More configuration variations

"````json
{
  "mcpServers": {
    "notifications": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/notification-mcp"],
      "env": {
        "MCP_NOTIFICATION_SOUND": "cosmic"
      }
    }
  }
}

Random sound each time

"````json
{
  "mcpServers": {
    "notifications": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/notification-mcp"],
      "env": {
        "MCP_NOTIFICATION_SOUND": "random"
      }
    }
  }
}

Use your own sound file

"````json
{
  "mcpServers": {
    "notifications": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/notification-mcp"],
      "env": {
        "MCP_NOTIFICATION_SOUND_PATH": "C:\\path\\to\\your\\sound.mp3"
      }
    }
  }
}

Environment variables

The following environment variables control which sound is played. You can set one to customize behavior. If you provide a custom path, that takes precedence over bundled sounds.

Sound options and files

Bundled sounds available include cosmic, fairy, gentle, pleasant, retro, and random. Sound files are included with the package, so you don’t need to download them separately.

Usage with the client

After the server is running, your MCP client can invoke the play_notification tool to emit a sound with an optional message, such as displaying a notification that a task has completed.

Development notes

If you are developing locally, you can run and test with npm scripts or npx. The server can be built, started, and inspected using the standard Node.js tooling provided in your project setup.

Sound library overview

The built-in sounds are stored under sounds/ and ship with the package. They cover a range of tones to suit different contexts, from soft defaults to more energetic notifications.

Troubleshooting tips

If a sound does not play, verify that MCP_NOTIFICATION_SOUND_PATH points to a valid MP3 file and that the server has permission to read it. Check that the environment is configured to use the intended sound and that the client is correctly requesting play_notification.

Available tools

play_notification

Play a notification sound to indicate task completion. Accepts an optional message and works with bundled sounds.