home / mcp / claude notifications mcp server

Claude Notifications MCP Server

Provides audible and visual notifications for Claude Desktop on macOS, with configurable sounds and macOS Notification Center alerts.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "charles-adedotun-notifications-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/path/to/server.py"
      ],
      "env": {
        "CLAUDE_START_SOUND": "default start sound path or system sound",
        "CLAUDE_COMPLETE_SOUND": "default complete sound path or system sound",
        "CLAUDE_NOTIFICATION_ICON": "/path/to/your/icon.png",
        "CLAUDE_VISUAL_NOTIFICATIONS": "true or false"
      }
    }
  }
}

You install and run a lightweight MCP server that delivers both audible and visual notifications to Claude Desktop on macOS. It keeps you informed when Claude starts processing and when it finishes a task, with customizable sounds, macOS Notification Center alerts, and a straightforward setup that requires minimal dependencies.

How to use

After installing, you run the notification server through the MCP client you use with Claude Desktop. The server offers a task_status notification tool that Claude calls at the start and end of each interaction, delivering an audible sound and a visual alert. You can customize sounds and icons, and you can choose to enable or disable visual notifications. To test the system, trigger the test workflow provided by the server to verify that all notification methods are functioning on your machine.

How to install

Prerequisites you need on macOS include Claude Desktop and Python 3.8 or higher. You also want a working internet connection for dependencies.

# Step 1: Clone the project
git clone https://github.com/charles-adedotun/notifications-mcp-server.git
cd notifications-mcp-server

# Step 2: Install uv (if not already installed)
# Option 1: Using curl
curl -LsSf https://astral.sh/uv/install.sh | sh

# Option 2: Using Homebrew
brew install uv

# Step 3: Install the package and dependencies
# Install the package in development mode
uv pip install -e .

# Or install directly from the repository
uv pip install git+https://github.com/charles-adedotun/notifications-mcp-server.git

# Install visual notification dependencies (recommended)
uv pip install pyobjc-core pyobjc-framework-Cocoa

# Step 4: Test the installation
# Run the test script to verify notifications are working
uv run python test_notification.py

# Run the notification server directly
uv run claude-notifications

# Step 5: Configure Claude Desktop
# Create or edit the Claude Desktop MCP configuration to include the notification server

Example integration snippet you would add to Claude Desktop configuration (path and exact location may vary):

{
  "mcpServers": {
    "notify-user": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/path/to/server.py"
      ]
    }
  }
}

Additional steps

Restart Claude Desktop after adding the server configuration to ensure the MCP connection is established.

Test the notifications to confirm everything is wired correctly:

uv run python test_notification.py

Available tools

task_status

Notification endpoint used by Claude Desktop to signal start and end of each interaction, triggering audible and visual alerts.

sound_manager

Handles playback of macOS system sounds or custom .aiff files for start and completion notifications.

notification_manager

Manages visual alerts via macOS Notification Center, with fallbacks to AppleScript or terminal-notifier if needed.

macos_integration

Platform-specific implementations for macOS including sound and notification methods using PyObjC, pync, AppleScript, and terminal-notifier.