Claude Notification Server
About
MCP server for macOS notifications and sounds when Claude Desktop tasks complete.
Details
- Author
- charles-adedotun
- GitHub stars
- 15
- Downloads
- 392
- Categories
- AI
Jump to
- Registers a task_status MCP tool.
- Plays macOS system sounds with afplay.
- Sends visual notifications using multiple fallback methods.
- Supports separate start and completion sounds.
- Supports disabling visual notifications via an environment variable.
- Includes tests for the modular notification and sound managers.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Claude Notification ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install the package with pip install notifications-mcp-server. Optionally install visual dependencies with pip install "notifications-mcp-server[visual]" and (for terminal-notifier) run brew install terminal-notifier. Configure Claude Desktop to run the console script claude-notifications. Customize behavior with environment variables CLAUDE_START_SOUND, CLAUDE_COMPLETE_SOUND, CLAUDE_VISUAL_NOTIFICATIONS, and CLAUDE_NOTIFICATION_ICON.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"claude notification server": {
"notifications-mcp-server": {
"command": "uv",
"args": [
"pip",
"install",
"-e",
"."
]
}
}
}
}McpServers
{
"notifications-mcp-server": {
"command": "uv",
"args": [
"pip",
"install",
"-e",
"."
]
}
}Notifications MCP Server
MCP server that lets Claude Desktop or another MCP client trigger macOS sound and visual notifications through a task_status tool.
Current Status
This is a macOS-focused utility. It is not an automatic Claude completion detector by itself: an MCP client or model must call the task_status tool when it wants a notification.
What Works Today
- Registers a task_status MCP tool.
- Plays macOS system sounds with afplay.
- Sends visual notifications using terminal-notifier, AppleScript, PyObjC, or pync fallbacks.
- Supports separate start and completion sounds.
- Supports disabling visual notifications through an environment variable.
- Includes tests for the modular notification and sound managers.
Important Limitations
- macOS is the only implemented platform.
- Linux and Windows support are not implemented.
- Notifications only happen when the MCP tool is called.
- The packaged console script is claude-notifications.
- The Python package is notifications; there is no notifications_mcp_server module entry point.
- Custom sound configuration uses environment variables, not the JSON configuration block that older README versions showed.
Installation
pip install notifications-mcp-server
Optional visual notification dependencies:
pip install "notifications-mcp-server[visual]"
pip install "notifications-mcp-server[pync]"
For terminal-notifier fallback support:
brew install terminal-notifier
Claude Desktop Configuration
Use the console script installed by the package:
{
"mcpServers": {
"notifications": {
"command": "claude-notifications"
}
}
}
Restart Claude Desktop after changing the config.
Configuration
Environment variables:
export CLAUDE_START_SOUND="/System/Library/Sounds/Glass.aiff"
export CLAUDE_COMPLETE_SOUND="/System/Library/Sounds/Hero.aiff"
export CLAUDE_VISUAL_NOTIFICATIONS="true"
export CLAUDE_NOTIFICATION_ICON="/path/to/icon.png"
If no custom sounds are set, the server uses macOS system sounds.
MCP Tool
task_status
Input:
{
"message": "Task completed"
}
Messages containing start or processing are treated as start notifications. Other messages are treated as completion notifications.
Verification Demo
Run the local diagnostic script on macOS to test the available notification paths:
python3 test_notification.py
The MCP tool returns a compact status object after attempting sound and visual notification delivery:
{
"status": "success",
"message": "Task completed",
"sound": "/System/Library/Sounds/Hero.aiff",
"visual": true
}
For a quieter smoke test that skips visual notification prompts:
CLAUDE_VISUAL_NOTIFICATIONS=false claude-notifications
Development
git clone https://github.com/charles-adedotun/notifications-mcp-server.git
cd notifications-mcp-server
pip install -e ".[dev]"
pytest
License
MIT
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
