What is Notification Mcp

notification-mcp is a Model Context Protocol server that enables AI agents to play notification sounds when tasks are completed.

Use cases

Use cases include notifying users of completed tasks in project management tools, alerting users in AI-driven applications, and enhancing user experience in automation systems.

How to use

To use notification-mcp, configure the MCP client by setting the ‘MCP_NOTIFICATION_SOUND_PATH’ environment variable to the desired sound file path in your ‘MCP_config.json’. You can use provided sound files or your own MP3 files.

Key features

Key features include the ‘play_notification’ tool that plays a notification sound upon task completion, supports cross-platform playback on Windows and macOS, and allows customizable notification sounds.

Where to use

notification-mcp can be used in various applications where task completion notifications are beneficial, such as productivity tools, AI assistants, and automated workflows.

✨ Notifications MCP Server ✨

Dream it, Pixel it. Made with ❤️ by Pink Pixel.

Overview

A Model Context Protocol server that allows AI agents to play notification sounds when tasks are completed. This TypeScript-based MCP server provides a simple, configurable notification system with bundled sounds that work out of the box with npx!

✨ Features

🔧 Tools

• play_notification - Play a notification sound to indicate task completion
  • Takes an optional message parameter to display with the notification
  • Supports cross-platform sound playback (Windows and macOS)
  • Works with bundled sounds - no manual downloads required!

🎵 Built-in Sound Library

5 high-quality notification sounds bundled with the package:

• cosmic - Space-themed notification 🌌
• fairy - Magical, whimsical tone 🧚‍♀️
• gentle - Soft, pleasant default sound (default) 🔔
• pleasant - Balanced, professional tone 📞
• retro - Nostalgic, vintage-style notification 🕹️
• random - Randomly plays one of the 5 sounds 🎲

🚀 Quick Start

Option 1: Use Bundled Sounds (Recommended) ⭐

Just run it with npx - sounds included!

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

Option 2: Choose a Different Bundled Sound

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

Option 3: Random Sound Each Time 🎲

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

Option 4: Use Your Own Custom Sound

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

⚙️ Configuration

The notification sound can be configured using environment variables:

Environment Variables

Priority Order

1. Custom Path (MCP_NOTIFICATION_SOUND_PATH) - highest priority
2. Bundled Sound (MCP_NOTIFICATION_SOUND) - choose from 5 included sounds
3. Default - gentle chime if nothing is specified

💻 Usage

Once configured, your MCP client can call the play_notification tool:

await client.request({
  method: "tools/call",
  params: {
    name: "play_notification",
    arguments: {
      message: "Task completed successfully! 🎉"
    }
  }
});

🛠️ Development

Local Development Setup

# Clone the repository
git clone https://github.com/pinkpixel-dev/notification-mcp.git
cd notification-mcp

# Install dependencies
npm install

# Build the server
npm run build

# For development with auto-rebuild
npm run watch

Local Development Configuration

{
  "mcpServers": {
    "notifications": {
      "command": "node",
      "args": [
        "./build/index.js"
      ],
      "env": {
        "MCP_NOTIFICATION_SOUND": "retro"
      }
    }
  }
}

Debugging

Use the MCP Inspector for interactive debugging:

npm run inspector

The Inspector provides a web interface to test your MCP server in your browser.

📦 Installation Methods

NPX (Recommended)

No installation required - sounds are bundled automatically:

npx @pinkpixel/notification-mcp

Global Install

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

Local Install

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

🎵 Sound Files

All sound files are located in the sounds/ directory and are automatically included when you install the package:

• Cosmic: sounds/cosmic_chime.mp3 - 🌌 Space-themed
• Fairy: sounds/fairy_chime.mp3 - 🧚‍♀️ Magical
• Gentle: sounds/gentle_chime.mp3 - 🔔 Default (soft)
• Pleasant:sounds/pleasant_chime.mp3 - 📞 Professional
• Retro: sounds/retro_chime.mp3 - 🕹️ Vintage
• Random: Set MCP_NOTIFICATION_SOUND=random - 🎲 Surprise me!

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 About Pink Pixel

• Website: pinkpixel.dev
• GitHub: github.com/pinkpixel-dev
• Discord: @sizzlebop

Made with ❤️ by Pink Pixel ✨