https://github.com/charles-adedotun/notifications-mcp-server
A Model Context Protocol (MCP) server that provides notifications for Claude Desktop on macOS. It plays configurable system sounds when Claude completes a task, enhancing user experience by eliminating the need for constant visual monitoring.
https://github.com/charles-adedotun/notifications-mcp-server
claude llm-tools macos mcp notification-system python
Last synced: about 2 months ago
JSON representation
A Model Context Protocol (MCP) server that provides notifications for Claude Desktop on macOS. It plays configurable system sounds when Claude completes a task, enhancing user experience by eliminating the need for constant visual monitoring.
- Host: GitHub
- URL: https://github.com/charles-adedotun/notifications-mcp-server
- Owner: charles-adedotun
- License: mit
- Created: 2025-03-16T23:20:46.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-12-10T18:47:46.000Z (6 months ago)
- Last Synced: 2025-12-11T05:47:30.364Z (6 months ago)
- Topics: claude, llm-tools, macos, mcp, notification-system, python
- Language: Python
- Homepage:
- Size: 167 KB
- Stars: 11
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-mcp-servers - **notifications-mcp-server** - A Model Context Protocol (MCP) server that provides notifications for Claude Desktop on macOS. It plays configurable system sounds when Claude completes a task, enhancing user experience by eliminating the need for constant visual monitoring. `python` `claude` `llm-tools` `macos` `mcp` `pip install git+https://github.com/charles-adedotun/notifications-mcp-server` (🤖 AI/ML)
README
# Notifications MCP Server
[](https://github.com/charles-adedotun/notifications-mcp-server/actions/workflows/python-test.yml)
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
```json
{
"notifications": {
"enabled": true,
"sound": true,
"sound_file": "Glass",
"volume": 0.7
}
}
```
## Quick Start
### Installation
```bash
pip install notifications-mcp-server
```
### Configuration
Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```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
1. **Modular Platform Support** - Clean abstraction for future Linux/Windows support
2. **Zero Configuration** - Works out of box with sensible defaults
3. **Non-Blocking** - Never delays Claude's operations
4. **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/`:
```bash
mkdir -p ~/.config/notifications-mcp/sounds
cp my-notification.wav ~/.config/notifications-mcp/sounds/
```
Update config to use custom sound:
```json
{
"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
```bash
# 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
1. Check macOS Notification Center permissions
2. Verify Claude Desktop config syntax
3. Check server logs: `tail -f ~/.config/notifications-mcp/logs/server.log`
### Sound Not Playing
1. Verify sound file exists
2. Check volume settings
3. 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