<div align="center">

# ✨ Notifications MCP Server ✨

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

</div>

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

| Variable | Description | Default |
|----------|-------------|---------|
| MCP_NOTIFICATION_SOUND | Choose from bundled sounds: cosmic, fairy, gentle, pleasant, retro, random | gentle |
| MCP_NOTIFICATION_SOUND_PATH | Absolute path to your own MP3 file (overrides bundled sounds) | null |

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 ✨