Skip to main content
Glama
charles-adedotun

Notifications MCP Server

by charles-adedotun
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

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

Available Tools

1 tool
task_statusA

ā€¼ļø 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.

Args: message (str): Message describing the state of the task (e.g., "Started processing", "Task completed")

Returns: dict: Status information about the notification

ParametersJSON Schema
NameRequiredDescriptionDefault
messageNoTask completed

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses the tool sends notifications (sound and visual) and its mandatory nature. However, missing details like side effects (e.g., does it interrupt users?), rate limits, or permissions needed. Adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Overly verbose with repeated warnings and instructions. Could be concise: single sentence for usage guidelines and a brief parameter explanation. Use of emoji and formatting adds unnecessary length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple notification tool with one optional param and output schema, description covers purpose, usage instructions, parameter semantics, and return type. However, output schema exists but description only gives vague 'Status information' ā€” still adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter 'message' with no schema description (0% coverage). Description adds value by explaining its purpose ('Message describing state of the task') and providing examples ('Started processing', 'Task completed'). Also mentions default 'Task completed' from schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool sends notifications (sound and visual) to alert users of LLM processing state. The verb 'sends' and resource 'notifications' are specific. No sibling tools for differentiation, but purpose is unmistakable despite name 'task_status' being slightly ambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Extremely explicit instructions: call at start of every response, before other tools, at end of conversations, even if no other tools used. No ambiguity about when to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.1.0
    • First observedtask_status
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0
Disambiguation5/5

Only one tool exists, so there is no ambiguity with other tools. The tool's purpose is clearly described.

Naming Consistency2/5

The tool name 'task_status' suggests checking status, but the tool actually sends notifications. This mismatch between name and function indicates poor naming consistency.

Tool Count3/5

A single tool for a notifications server is borderline. It might be sufficient for simple task notifications, but the scope is narrow.

Completeness2/5

The server only covers task status notifications, missing other common notification types (e.g., errors, warnings, arbitrary messages). This is a significant gap.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • macOS Notify MCP

    yuki-yano
    A
    license
    B
    quality
    F
    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
    17
    14
    MIT

  • MCP Notifications Server

    konstzv
    F
    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
    16
    -

  • mcp-ding

    zhuqingyv
    F
    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.
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/charles-adedotun/notifications-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server