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
Metadata
Release files for iflow-mcp_charles-adedotun-notifications-mcp-server 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_charles_adedotun_notifications_mcp_server-1.2.0.tar.gz | 16.4 kB | Without provenance | Details for iflow_mcp_charles_adedotun_notifications_mcp_server-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_charles_adedotun_notifications_mcp_server-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_charles_adedotun_notifications_mcp_server-1.2.0-py3-none-any.whl |
Total release size: 35.3 kB
Release files / iflow_mcp_charles_adedotun_notifications_mcp_server-1.2.0.tar.gz
| Download URL | iflow_mcp_charles_adedotun_notifications_mcp_server-1.2.0.tar.gz |
|---|---|
| Size | 16.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b1bb8765d2f344472cf82b57afd56cba6fb2dd0c4f6ee8120d0c524bed4aaa43
|
|
BLAKE2b-256 checksum How to use checksums |
57bcc87a05b2f3068ab961453c8a189975364e547986467ec11054d5fb42001d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_charles_adedotun_notifications_mcp_server-1.2.0-py3-none-any.whl
| Download URL | iflow_mcp_charles_adedotun_notifications_mcp_server-1.2.0-py3-none-any.whl |
|---|---|
| Size | 18.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
99b89c6b9702fe7d2c0d816fbe5263fad9f10ab878acb7f13967cdbd19f40c68
|
|
BLAKE2b-256 checksum How to use checksums |
7ff21258f55403cce338dcf09ff63b51fb29c4df383dbc0b1db5d4f82c384e0b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_charles-adedotun-notifications-mcp-server 1.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.