https://github.com/pinkpixel-dev/notification-mcp
A Model Context Protocol server that allows AI agents to play a notification sound via a tool when a task is completed.
https://github.com/pinkpixel-dev/notification-mcp
agent ai llm mcp mcp-server mcp-tools model-context-protocol model-context-protocol-servers nodejs notifications sound typescript
Last synced: 4 months ago
JSON representation
A Model Context Protocol server that allows AI agents to play a notification sound via a tool when a task is completed.
- Host: GitHub
- URL: https://github.com/pinkpixel-dev/notification-mcp
- Owner: pinkpixel-dev
- Created: 2025-05-30T04:34:45.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-05-30T05:15:49.000Z (4 months ago)
- Last Synced: 2025-05-30T05:52:33.681Z (4 months ago)
- Topics: agent, ai, llm, mcp, mcp-server, mcp-tools, model-context-protocol, model-context-protocol-servers, nodejs, notifications, sound, typescript
- Language: JavaScript
- Homepage: https://pinkpixel.dev
- Size: 44.9 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-mcp-servers - **notification-mcp** - A Model Context Protocol server that allows AI agents to play a notification sound via a tool when a task is completed. `javascript` `agent` `ai` `llm` `mcp` `npm install pinkpixel-dev/notification-mcp` (AI/ML)
- awesome-mcp-servers - **notification-mcp** - A Model Context Protocol server that allows AI agents to play a notification sound via a tool when a task is completed. `javascript` `agent` `ai` `llm` `mcp` `npm install pinkpixel-dev/notification-mcp` (AI/ML)
README
# ✨ Notifications MCP Server ✨
**Dream it, Pixel it. Made with ❤️ by Pink Pixel.**
[](LICENSE) [](https://github.com/model-context-protocol/model-context-protocol) [](https://www.npmjs.com/package/@pinkpixel/notification-mcp) [](https://smithery.ai/server/@pinkpixel-dev/notification-mcp)
[](https://www.typescriptlang.org/) [](https://nodejs.org/) [](https://www.npmjs.com/package/@pinkpixel/notification-mcp)
[](https://www.npmjs.com/package/@pinkpixel/notification-mcp) [](https://github.com/pinkpixel-dev/notification-mcp/stargazers) [](https://github.com/pinkpixel-dev/notification-mcp/issues) [](http://makeapullrequest.com)
[](https://github.com/pinkpixel-dev/notification-mcp) [](https://pinkpixel.dev) [](https://pinkpixel.dev)
## 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!
```json
{
"mcpServers": {
"notifications": {
"command": "npx",
"args": ["-y", "@pinkpixel/notification-mcp"]
}
}
}
```
### Option 2: Choose a Different Bundled Sound
```json
{
"mcpServers": {
"notifications": {
"command": "npx",
"args": ["-y", "@pinkpixel/notification-mcp"],
"env": {
"MCP_NOTIFICATION_SOUND": "cosmic"
}
}
}
}
```
### Option 3: Random Sound Each Time 🎲
```json
{
"mcpServers": {
"notifications": {
"command": "npx",
"args": ["-y", "@pinkpixel/notification-mcp"],
"env": {
"MCP_NOTIFICATION_SOUND": "random"
}
}
}
}
```
### Option 4: Use Your Own Custom Sound
```json
{
"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:
```typescript
await client.request({
method: "tools/call",
params: {
name: "play_notification",
arguments: {
message: "Task completed successfully! 🎉"
}
}
});
```
## 🛠️ Development
### Local Development Setup
```bash
# 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
```json
{
"mcpServers": {
"notifications": {
"command": "node",
"args": ["./build/index.js"],
"env": {
"MCP_NOTIFICATION_SOUND": "retro"
}
}
}
}
```
### Debugging
Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for interactive debugging:
```bash
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:
```bash
npx @pinkpixel/notification-mcp
```
### Global Install
```bash
npm install -g @pinkpixel/notification-mcp
notification-mcp
```
### Local Install
```bash
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](CONTRIBUTING.md) for guidelines.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🌟 About Pink Pixel
- **Website:** [pinkpixel.dev](https://pinkpixel.dev)
- **GitHub:** [github.com/pinkpixel-dev](https://github.com/pinkpixel-dev)
- **Discord:** @sizzlebop
---
*Made with ❤️ by Pink Pixel* ✨