Mcp Notifications

io.github.topvisorPublished by GitHub account topvisorv1.0.3Updated Oct 24, 2026

MCP server for desktop notifications over stdio

VerifiedSTDIODesktop onlyProductivity & WorkflowDeveloper Tools

Overview

AI-generated overview

A local stdio MCP server that lets an AI agent send native desktop notifications when a task finishes, fails, or needs your input.

What you can do
  • Send desktop notifications with a title and message, optionally with a sound, a custom icon, and a Windows app_id source label.
  • Queue notifications in the background so the agent gets a quick "Notification queued" result instead of blocking.
  • Choose the delivery backend through an environment variable: automatic, PowerShell toasts, or the node-notifier package.
  • Use it manually by asking the agent to notify you, or automatically by adding instructions to chats, projects, or skills.
When to use it
Useful when you run long or multi-step agent tasks in a console client that has no built-in notifications and you do not want to keep checking the chat. It is meant for desktop use, mainly to signal completion, failures, or requests for input.
Requirements
Runs as a local process over stdio, installed globally from npm as @topvisor/mcp-notifications; needs Node.js 20 or newer and npm 10 or newer. The executable mcp-notifications must be added to the MCP client config (for example Codex or Claude) and the client restarted. Optional environment variables MCP_NOTIFICATIONS_BACKEND and MCP_NOTIFICATIONS_APP_ID tune the backend and Windows toast source.
Before you install
Notifications appear on the machine running the server, so anything the agent puts in a title or message becomes visible on your desktop, including task details or summaries. Automatic notification instructions can produce frequent pop-ups and sounds if the threshold is set loosely. The optional icon path is read from the local filesystem. No credentials or network access are declared.

Installation

In SourceWeft

  1. Open Mcp Notifications in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-notifications

[npm version]

🚀 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
bash
npm i -g @topvisor/mcp-notifications

Executable name (use this in MCP config):

bash
mcp-notifications

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

Setup: Codex

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

toml
[mcp_servers.notifications]enabled = truecommand = "mcp-notifications"args = []

Restart Codex after config update.

Setup: Claude Agent

Add MCP server config to your Claude client config file:

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

text
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:

text
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:

text
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:

text
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:

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

text
Check send_notification
text
Send a notification without sound: title "Test", message "Check"
text
Send a notification with sound: title "Test", message "Check"
text
Send a notification with app_id "Topvisor.Codex": title "Test", message "Check"
text
Send 3 test notifications in a row without sound

Expected tool result in logs/response:

text
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:

[example.png]

Source: README.md at commit 9cd5ee5

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.3LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts