Notifications MCP Server
README.md
<div align="center">
<img src="./icon.png" alt="Notification MCP Logo" width="300"/>
# ✨ 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)
</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
- `notify` - Show a desktop toast notification and/or play a sound when tasks complete (Recommended for summaries)
- `message` (required): The notification message/summary of the completed task
- `title` (optional): The title for the toast notification (defaults to "Task Completed")
- `mode` (optional): `"toast" | "sound" | "both"` (defaults to `"both"`)
- `sound` (optional): Name of the sound to play, which overrides default settings
- Fully supports Windows, macOS, and Linux out of the box!
- `play_notification` - Play a notification sound to indicate task completion
- Takes an optional `message` parameter to log/display with the notification
- Supports cross-platform sound playback (Windows, macOS, and Linux)
- **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 either the unified `notify` tool or the audio-only `play_notification` tool:
### 1. Unified Toast + Sound Notification (Recommended)
```typescript
await client.request({
method: "tools/call",
params: {
name: "notify",
arguments: {
title: "Build Succeeded",
message: "Antigravity successfully tested the package version 0.2.0! 🚀",
mode: "both", // "toast", "sound", or "both"
sound: "cosmic" // optional override
}
}
});
```
### 2. Audio-Only Notification
```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 dual-licensed under the MIT and Apache 2.0 Licenses - 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* ✨
TDQS
B3.2/5.0
Scored across 1 tool
Disambiguation5/5
With only one tool, there is no possibility of confusion or overlap between tools, as there are no other tools to compare it against. The tool's purpose is clearly defined and stands alone without ambiguity.
Naming Consistency5/5
Since there is only one tool, naming consistency is inherently perfect; there are no other tool names to compare it to, and it follows a clear verb_noun pattern (play_notification). No inconsistencies can exist in a single-tool set.
Tool Count2/5
A single tool for a 'Notifications MCP Server' feels thin and under-scoped, as it only provides a basic playback function without supporting operations like listing, creating, or managing notifications. This minimal set limits functionality and may not fully cover the expected domain of notifications.
Completeness2/5
The tool surface is severely incomplete for a notifications server, lacking essential operations such as creating, listing, updating, or deleting notifications. With only a playback tool, agents cannot perform basic CRUD or lifecycle management, leading to significant gaps in functionality.
Maintenance
ActivityStale
ResponsivenessNo issues