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.

Recommended profile action: keep as a focused utility repo. Suggested topics: mcp, claude, claude-desktop, macos, notifications, python.

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.

Development

git clone https://github.com/charles-adedotun/notifications-mcp-server.git
cd notifications-mcp-server
pip install -e ".[dev]"
pytest

License

MIT