Notifications MCP Server
You can use this macOS-only MCP server to trigger sound and visual notifications when an MCP client calls the task_status tool.
Send start or completion notifications by passing an optional
message; messages containingstartorprocessingare treated as start notifications, others as completion.Play separate configurable macOS sounds for start and completion via
CLAUDE_START_SOUNDandCLAUDE_COMPLETE_SOUND.Show visual notifications using terminal-notifier, AppleScript, PyObjC, or pync fallbacks, or disable them with
CLAUDE_VISUAL_NOTIFICATIONS=false.Customize the notification icon with
CLAUDE_NOTIFICATION_ICON.Receive a compact status object after the server attempts sound and visual delivery.
Note: notifications occur only when the tool is invoked; there is no automatic completion detection, and Linux/Windows are unsupported.
Triggers macOS sound and visual notifications when tasks start or complete.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Notifications MCP Server send a notification when the long-running script finishes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: macOS Notify MCP
What Works Today
Registers a
task_statusMCP 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 nonotifications_mcp_servermodule 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-notificationsOr 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-notifierClaude 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.pyThe 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-notificationsDevelopment
git clone https://github.com/charles-adedotun/notifications-mcp-server.git
cd notifications-mcp-server
pip install -e ".[dev]"
pytestLicense
MIT
Available Tools
1 tooltask_statusTask StatusC
âźď¸ MANDATORY: Sends notifications (sound and visual) for the user.
đ˘ IMPORTANT INSTRUCTIONS FOR THE LLM:
ALWAYS call this tool at the START of EVERY response
Call this tool BEFORE using any other tools
Call this tool at the END of conversations
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
Scored across 1 tool
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.
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.
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.
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
Related MCP Connectors
Nifty's MCP server â exposes tasks, projects, messages, and files as tools for AI agents.
Push notifications for AI agents - send instant iPhone notifications from any MCP client.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for Clipkit â gives AI agents a video toolbox via the Clipkit schema.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenancemacOS Notification MCP enables AI assistants to trigger native macOS sounds, visual notifications, and text-to-speech. Built for Claude and other AI models using the Model Context Protocol.39MIT
- AlicenseBqualityDmaintenanceAn 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.324 npm14MIT
- AlicenseBqualityDmaintenanceEnables Claude and other MCP clients to display native macOS notifications with customizable titles, messages, icons, and sounds through the macOS Notification Center.1MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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