mcp-os-notifications

An MCP server that lets LLM agents dispatch native OS notifications when a task finishes. If you tell your agent, "do this and notify me when done", it will.

Works with Claude Code, Claude Desktop, OpenCode, or any other MCP client.

What it does

• Exposes a single MCP tool: dispatch_os_notification.

• Detects when you ask to be notified ("notify me when done", "ping me when finished", etc.).

• Sends a native desktop notification once the agent finishes its work.

• Task tokens: reuse a token to update an existing notification instead of spamming new ones. Great for progress updates.

• Mobile bridge: optionally push to ntfy.sh, Telegram, or Pushover when you are away from your desk.

• Quiet hours: suppress non-critical desktop notifications during configured hours; critical ones still come through.

• Cross-platform: Linux (DBus/FreeDesktop notifications), macOS, Windows.

Related MCP server: mcp-macos-utils

How it works

1. The MCP server runs locally as a stdio subprocess of your agent.

2. Project-level agent instructions (.claude/CLAUDE.md, skills/notify-when-done.md) teach the agent when to call the tool.

3. When the work is done, the agent calls dispatch_os_notification(title, message).

4. The server uses the native notification backend on your OS to show the toast/banner.

Requirements

• Python 3.10+

• uv (recommended for development) or pip

• A notification daemon on Linux (e.g., mako, dunst, GNOME/KDE built-in)

Install on a new machine

Option A: clone + uv (recommended for development)

git clone https://github.com/ekomac/mcp-os-notifications.git
cd mcp-os-notifications
uv sync
uv run mcp-os-notifications

Option B: clone + pip

git clone https://github.com/ekomac/mcp-os-notifications.git
cd mcp-os-notifications
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
mcp-os-notifications

Option C: install from GitHub without cloning

python3 -m pip install git+https://github.com/ekomac/mcp-os-notifications.git
mcp-os-notifications

Note: If you install from PyPI in the future (once published), the command is simply pip install mcp-os-notifications.

Verify the server starts

The server runs over stdio and waits for MCP messages. Press Ctrl+C to stop.

# If using uv in the repo
uv run mcp-os-notifications

# If installed globally with pip
mcp-os-notifications

Add to Claude Code

Claude Code reads .mcp.json at project scope or ~/.claude.json at user scope.

Project scope (recommended per repo)

If you open this repository directly in Claude Code, the bundled .mcp.json already registers the server. Just ask:

Build a quick Python script that prints the current time and notify me when done.

To use it in a different project while keeping the source in this repo, copy the snippet below into that project's .mcp.json and replace /ABSOLUTE/PATH/TO/mcp-os-notifications:

{
  "mcpServers": {
    "os-notifications": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/mcp-os-notifications",
        "run",
        "mcp-os-notifications"
      ]
    }
  }
}

User scope (global for all projects)

If you installed globally with pip or uv tool, add the command directly:

claude mcp add --transport stdio os-notifications mcp-os-notifications

Or if you keep the cloned repo:

claude mcp add --transport stdio os-notifications uv --directory /ABSOLUTE/PATH/TO/mcp-os-notifications run mcp-os-notifications

Check that it loaded

claude mcp list

You should see os-notifications with the dispatch_os_notification and notify_user tools.

Add to Claude Desktop

Add the server to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %AppData%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json (or $XDG_CONFIG_HOME/Claude/claude_desktop_config.json)

If installed globally with pip:

{
  "mcpServers": {
    "os-notifications": {
      "command": "mcp-os-notifications"
    }
  }
}

If using the cloned repo with uv:

{
  "mcpServers": {
    "os-notifications": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/mcp-os-notifications",
        "run",
        "mcp-os-notifications"
      ]
    }
  }
}

Add to OpenCode

OpenCode supports MCP servers via stdio. Add this to your OpenCode MCP configuration:

{
  "mcpServers": {
    "os-notifications": {
      "command": "mcp-os-notifications"
    }
  }
}

If you run from the cloned repo instead:

{
  "mcpServers": {
    "os-notifications": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/mcp-os-notifications",
        "run",
        "mcp-os-notifications"
      ]
    }
  }
}

Then copy the skill reference so OpenCode knows when to use the tool:

mkdir -p ~/.config/opencode/skills/notify-when-done
cp skills/notify-when-done.md ~/.config/opencode/skills/notify-when-done/SKILL.md

Other MCP clients

Any client that supports stdio MCP servers can use one of these commands:

# Installed globally
mcp-os-notifications

# From the cloned repo with uv
uv --directory /ABSOLUTE/PATH/TO/mcp-os-notifications run mcp-os-notifications

# From the cloned repo with pip venv
.venv/bin/mcp-os-notifications

Tool schema

The server exposes two identical tools; notify_user is a convenience alias for dispatch_os_notification.

dispatch_os_notification

Example tool calls

Simple completion notification

{
  "title": "Build finished",
  "message": "All 42 tests passed.",
  "urgency": "normal",
  "sound": true
}

Progress updates with a token

{
  "title": "Syncing files...",
  "message": "25 of 100 files processed",
  "token": "file-sync-job"
}

Then later with the same token:

{
  "title": "Sync complete",
  "message": "All 100 files uploaded",
  "token": "file-sync-job"
}

Critical + mobile push

{
  "title": "Build failed",
  "message": "Production deployment failed on the test stage.",
  "urgency": "critical",
  "mobile": true
}

Mobile bridge

The server can push notifications to mobile/remote backends alongside the desktop toast. This is useful when you are away from the computer. Configure one or more backends via environment variables.

ntfy.sh

export MCP_OS_NOTIFICATIONS_NTFY_URL="https://ntfy.sh/my-secret-topic"

You can also use a self-hosted ntfy instance:

export MCP_OS_NOTIFICATIONS_NTFY_URL="https://ntfy.example.com/alerts"

Telegram

export MCP_OS_NOTIFICATIONS_TELEGRAM_BOT_TOKEN="123456:ABC..."
export MCP_OS_NOTIFICATIONS_TELEGRAM_CHAT_ID="123456789"

Pushover

export MCP_OS_NOTIFICATIONS_PUSHOVER_USER_KEY="uQiRz..."
export MCP_OS_NOTIFICATIONS_PUSHOVER_APP_TOKEN="azGDO..."

Usage

Once a backend is configured, set mobile: true in the tool call. The server will notify every configured backend in parallel.

Passing environment variables to the server

Mobile and quiet-hours settings are read from the environment of the MCP server process. How you set them depends on the client:

• Claude Code: environment variables are inherited from the shell where you launched claude, or you can set them in the .mcp.json env block:

  {
    "mcpServers": {
      "os-notifications": {
        "type": "stdio",
        "command": "mcp-os-notifications",
        "env": {
          "MCP_OS_NOTIFICATIONS_NTFY_URL": "https://ntfy.sh/my-topic"
        }
      }
    }
  }

• Claude Desktop: use the env block in claude_desktop_config.json:

  {
    "mcpServers": {
      "os-notifications": {
        "command": "mcp-os-notifications",
        "env": {
          "MCP_OS_NOTIFICATIONS_NTFY_URL": "https://ntfy.sh/my-topic"
        }
      }
    }
  }

• OpenCode / other clients: set the variables in the shell before launching the client, or use the client's equivalent MCP environment settings.

Quiet hours

Suppress non-critical desktop notifications during a configured time window. Critical notifications still come through.

export MCP_OS_NOTIFICATIONS_QUIET_START="22:00"
export MCP_OS_NOTIFICATIONS_QUIET_END="07:00"

The window can span midnight (e.g., 22:00 to 07:00). Mobile pushes are not affected by quiet hours.

See Passing environment variables to the server above for how to expose these variables to the MCP server process.

Project structure

.
├── src/mcp_os_notifications/
│   ├── server.py                # MCP server and tools
│   ├── mobile.py                # Mobile/remote notification backends
│   └── quiet_hours.py           # Do-not-disturb logic
├── skills/notify-when-done.md   # Generic agent skill reference
├── .claude/CLAUDE.md            # Claude Code project instructions
├── .mcp.json                    # Project-scoped Claude Code MCP config
├── .github/workflows/ci.yml     # GitHub Actions CI
├── Makefile                     # Common dev commands
├── pyproject.toml
├── README.md
└── LICENSE

Development

A Makefile is provided for convenience:

make install   # uv sync
make test      # uv run pytest
make lint      # uv run ruff check .
make run       # uv run mcp-os-notifications
make clean     # remove caches, venv, build artifacts

CI runs on GitHub Actions for Python 3.10–3.14.

Troubleshooting

Linux: "DBUS_SESSION_BUS_ADDRESS not set"

The server tries to auto-detect the session bus, but if that fails, make sure your notification daemon is running (e.g., mako, dunst, swaync). You can also set:

export DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/$(id - u)/bus"

No notification appears

1. Check that your OS has a notification service enabled.

2. Try running the server directly with verbose logging:

   MCP_OS_NOTIFICATIONS_LOG_LEVEL=DEBUG uv run mcp-os-notifications

3. Check your agent's tool call output for the success flag.

Publishing / adding to the MCP ecosystem

There is no "Anthropic marketplace" for MCP servers, but there are official and community registries:

modelcontextprotocol/servers no longer accepts third-party listings.

Prior art

This is not the first MCP notification server. Similar projects exist, e.g.:

• Cactusinhand/mcp_server_notify

• pinkpixel-dev/notification-mcp

• devizor/macOS-Notification-MCP

This repo focuses on:

• A clean, minimal Python implementation using desktop-notifier.

• Ready-to-use agent skill references for Claude Code and OpenCode.

• A project-scoped .mcp.json so Claude Code works out of the box.

• Task tokens to replace notifications instead of spamming.

• Mobile bridge to ntfy.sh, Telegram, and Pushover.

• Quiet hours to respect do-not-disturb time windows.

License

MIT — see LICENSE.