charles-adedotun/notifications-mcp-server
If you are the rightful owner of notifications-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.
A lightweight MCP server that provides both auditory and visual notifications for Claude Desktop on macOS.
Notifications MCP Server
MCP server that plays sounds and shows notifications when Claude Desktop completes tasks.
Why This Exists
You kick off a long Claude task and tab away to check email, review PRs, or write docs. Ten minutes later you realize Claude finished five minutes ago. This server fixes that. Sound plays, notification appears, you're back in action.
What It Does
Integrates with Claude Desktop to provide real-time completion feedback:
- System Notifications - Native macOS notifications when tasks complete
- Sound Alerts - Customizable audio feedback (success, error, warning tones)
- Task Status - Clear indication of completion state
- Non-Intrusive - Works in background, no polling required
Tech Stack
- Python 3.8+
- FastMCP for Model Context Protocol integration
- macOS Notification Center
- PyObjC for native system integration
Features
Notification Types
- Success - Task completed successfully
- Error - Task failed with error details
- Warning - Task completed with warnings
- Info - General task updates
Sound Options
- Built-in system sounds
- Custom sound file support
- Volume control
- Sound enable/disable toggle
Configuration
{
"notifications": {
"enabled": true,
"sound": true,
"sound_file": "Glass",
"volume": 0.7
}
}
Quick Start
Installation
pip install notifications-mcp-server
Configuration
Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"notifications": {
"command": "python",
"args": ["-m", "notifications_mcp_server"]
}
}
}
Restart Claude Desktop. Notifications are now active.
Architecture
notifications-mcp-server/
├── core/
│ ├── notification_manager.py # Notification logic
│ └── sound_manager.py # Audio playback
├── platform/
│ ├── macos.py # macOS integration
│ └── base.py # Platform interface
├── utils/
│ ├── config.py # Configuration management
│ └── logger.py # Logging utilities
└── server.py # MCP server entry point
Design Principles
- Modular Platform Support - Clean abstraction for future Linux/Windows support
- Zero Configuration - Works out of box with sensible defaults
- Non-Blocking - Never delays Claude's operations
- Fail Safe - Notification failures don't break Claude tasks
Platform Support
- macOS - Full support (notifications + sound)
- Linux - Planned (via notify-send)
- Windows - Planned (via Windows Toast)
Usage Examples
Claude Desktop automatically triggers notifications. No manual invocation needed.
Custom Sounds
Place custom audio files in ~/.config/notifications-mcp/sounds/:
mkdir -p ~/.config/notifications-mcp/sounds
cp my-notification.wav ~/.config/notifications-mcp/sounds/
Update config to use custom sound:
{
"notifications": {
"sound_file": "my-notification.wav"
}
}
Future Ideas
- Linux Support - Native notification support via libnotify
- Windows Support - Windows 10/11 Toast notifications
- Custom Sound Uploads - Web interface for managing notification sounds
- Slack Integration - Post completion updates to Slack channels
- Discord Integration - Send notifications to Discord webhooks
- Notification History - Track and review past task completions
- Smart Notifications - Only notify for tasks exceeding time threshold
- Team Notifications - Share task completion across team members
Development
# Clone repository
git clone https://github.com/charles-adedotun/notifications-mcp-server.git
cd notifications-mcp-server
# Install dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Type checking
mypy src/
Troubleshooting
Notifications Not Appearing
- Check macOS Notification Center permissions
- Verify Claude Desktop config syntax
- Check server logs:
tail -f ~/.config/notifications-mcp/logs/server.log
Sound Not Playing
- Verify sound file exists
- Check volume settings
- Test sound file:
afplay /path/to/sound.wav
Contributing
Found a bug? Open an issue with reproduction steps. Built Windows/Linux support? Submit a PR. Keep platform modules isolated and tested.
License
MIT
