Skip to main content
Glama
Notifications MCP Server

Notifications MCP Server

Notifications MCP Server

Tests

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.

Related MCP server: macOS Notify MCP

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

Run directly from GitHub with uvx (zero manual virtualenv setup required):

uvx --from git+https://github.com/charles-adedotun/notifications-mcp-server claude-notifications

Or install into your Python environment directly from GitHub:

pip install "git+https://github.com/charles-adedotun/notifications-mcp-server.git"

Optional visual notification dependencies:

pip install "notifications-mcp-server[visual] @ git+https://github.com/charles-adedotun/notifications-mcp-server.git"
pip install "notifications-mcp-server[pync] @ git+https://github.com/charles-adedotun/notifications-mcp-server.git"

For terminal-notifier fallback support on macOS:

brew install terminal-notifier

Claude Desktop / Claude Code Configuration

Configure via uvx (recommended):

{
  "mcpServers": {
    "notifications": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/charles-adedotun/notifications-mcp-server",
        "claude-notifications"
      ]
    }
  }
}

Or if installed globally via pip / uv tool install:

{
  "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

Available Tools

1 tool
task_statusTask StatusC

‼️ MANDATORY: Sends notifications (sound and visual) for the user.

📢 IMPORTANT INSTRUCTIONS FOR THE LLM:

  1. ALWAYS call this tool at the START of EVERY response

  2. Call this tool BEFORE using any other tools

  3. Call this tool at the END of conversations

  4. Use this tool even if no other tools are needed

⚠️ PURPOSE: This notification alerts users when the LLM has started or completed processing.

Inputs: message. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 1 tool

    Disambiguation5/5

    There is only one tool on the server, so there is no possibility of selecting the wrong tool. The tool's dual role (start and end notifications) is handled by a single surface, but that is a completeness issue rather than an ambiguity across tools.

    Naming Consistency4/5

    With a single tool there is no cross-tool inconsistency to penalize, and 'task_status' is a readable snake_case identifier. It is a noun phrase rather than the more typical verb_noun pattern, which keeps it slightly short of ideal.

    Tool Count3/5

    Notification is a narrow purpose where one tool can suffice, but a single tool conflating start-of-response and end-of-conversation signalling is borderline thin. A parameterized stage or separate start/complete operations would make the scope feel better earned.

    Completeness2/5

    The surface offers no way to specify notification stage, type (sound vs visual), or opt-out, so an agent cannot express the distinct events the description promises. For a notification domain, the lack of any start/complete distinction or configuration options is a significant gap.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that enables AI assistants like Claude to send native macOS notifications with tmux integration, allowing notifications to focus specific tmux sessions when clicked.
      3
      24 npm
      14
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables Claude and other MCP clients to display native macOS notifications with customizable titles, messages, icons, and sounds through the macOS Notification Center.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for macOS native notifications with 67 AI brand icons and system sound support, enabling AI agents to send desktop notifications via one-line tool calls.
      MIT