mcp-notifications

🚀 Ship faster. Miss nothing.

`mcp-notifications` lets your MCP agent send desktop notifications for completed tasks, failures, and important updates.

This is especially useful for console AI agents, because they usually have no built-in notifications by default.

No more checking chats every minute.

No more silent agent responses.

Just visible, reliable feedback on your desktop. 🔔

Common problem this solves

You give tasks to several AI agents, then wait and keep checking who already replied.

With `mcp-notifications`, this gets simpler: the agent can notify you on desktop when it needs your input or when work

is done.

Why teams install this

• ⚡ Immediate feedback from your MCP workflows.
• 🧠 Better focus: let the agent work while you stay on your main task.
• 🖥️ Native OS notifications via `node-notifier`.
• 🧵 Non-blocking behavior: notification sending is queued in background.

Install globally

Requirements:

• Node.js `>=20`
• npm `>=10`

npm i -g @topvisor/mcp-notifications

Executable name (use this in MCP config):

mcp-notifications

`mcp-notifications` is an MCP server entrypoint (`stdio`), not a one-shot notification command.

Setup: Codex

Add this to `~/.codex/config.toml`:

[mcp_servers.notifications]
enabled = true
command = "mcp-notifications"
args = []

Restart Codex after config update.

Setup: Claude Agent

Add MCP server config to your Claude client config file:

{
  "mcpServers": {
    "notifications": {
      "command": "mcp-notifications",
      "args": []
    }
  }
}

Then restart Claude client.

AI Agent Notification Instructions

There are two approaches to notifications: manual and automatic.

Choose the one that works better for your workflow.

Manual

In a task where you want to be notified, explicitly ask the agent. Example:

Count files in the project; after the task is fully complete, notify me with sound.

You can also define sound, topic, and frequency rules inside a specific chat. Example:

Notify me about your replies without sound, include the reply text, and use title: "Large Refactoring"

Automatic

Automatic notifications can be configured globally or per project.

Example instruction to enable automatic notifications for agent replies:

Send `send_notification` after your replies (actual task time >5 seconds or many steps); `play_sound: false`; `app_id: '{put your chat name here}'`

Time is a rough threshold and depends on model behavior, so adjust this instruction to your own preferences.

In Skills

You can also enable notifications in specific skills. Example for a Review skill:

After the review, run `send_notification` with a short summary; `play_sound: true`; `app_id: 'Reviewer {put task id here}'`

Tool

`send_notification`

Input:

• `title` `string` (required)
• `message` `string` (required)
• `play_sound` `boolean` (optional, default: `false`)
• `icon` `string` (optional, absolute or relative path to image file)
• `app_id` `string` (optional, Windows App User Model ID for toast source)

Example:

{
  "title": "Codex",
  "message": "Deployment completed successfully",
  "play_sound": true,
  "icon": "/opt/mcp-notifications/icons/custom.png",
  "app_id": "Topvisor.Codex"
}

app_id (Windows)

• `app_id` controls the source shown in Windows toast notifications.
• If `app_id` is not set, Windows may show `SnoreToast` as the source.
• You can pass `app_id` in each tool call, or set `MCP_NOTIFICATIONS_APP_ID` as an environment variable for the server.

Backend selection

You can select notification transport via env `MCP_NOTIFICATIONS_BACKEND`:

• `auto` (default): uses `powershell` in WSL if available, otherwise `node-notifier`
• `powershell`: force `powershell.exe` Windows toast transport (recommended for WSL)
• `node-notifier`: force `node-notifier` package

Chat Prompts To Test In Codex

Use these messages directly in chat:

Check send_notification

Send a notification without sound: title "Test", message "Check"

Send a notification with sound: title "Test", message "Check"

Send a notification with app_id "Topvisor.Codex": title "Test", message "Check"

Send 3 test notifications in a row without sound

Expected tool result in logs/response:

Notification queued

Behavior

• ✅ Uses standard system notification channels.
• 🔊 Uses the standard system notification sound when `play_sound: true`.
• 🤖 Uses bundled Topvisor robot image as default notification icon.
• 🧰 Returns quickly while notifications are delivered in background queue.

Example

The AI agent is waiting for you: