home / mcp / mcp notifications

MCP Notifications

Provides desktop notifications for MCP task updates, completions, and errors via system notification channels.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "artemeey-mcp-notifications": {
      "command": "mcp-notifications",
      "args": [],
      "env": {
        "MCP_NOTIFICATIONS_APP_ID": "Topvisor.Codex"
      }
    }
  }
}

You can add desktop notifications to your MCP workflows so you receive immediate feedback on task status, failures, and important updates. This MCP server runs locally and sends system notifications, helping you stay informed without constantly checking chats or consoles.

How to use

You run the MCP notifications server locally and configure your MCP clients to call it. When a task completes or an important event occurs, a desktop notification is generated and delivered in the background, so your work on other tasks stays uninterrupted.

How to install

Prerequisites: you need Node.js version 20 or higher and npm version 10 or higher.

Install the MCP notifications server globally so you can invoke it from any MCP client.

npm i -g @topvisor/mcp-notifications

Additional sections

Configure your MCP clients to use the notifications server. The executable is designed to be an MCP server entrypoint (stdio). You do not use it as a one-shot notification command.

Codex configuration example shows how to enable and point Codex at the server. After updating the configuration, restart Codex to apply changes.

Claude Agent configuration example shows how to add the MCP notifications server to the client configuration and then restart the client.

You can choose between manual and automatic notification approaches to suit your workflow. Manual approach prompts the agent to notify you when needed. Automatic approach allows global or project-specific default behavior for notifications.

Tool: send_notification enables you to push a desktop notification with fields like title, message, and optional settings such as play_sound, icon, and app_id.

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

Usage prompts to test in Codex

You can test the notification flow by sending a test request to the server through Codex with simple prompts like Check send_notification or Send a notification with sound. The expected result in logs is that the notification is queued.

Available tools

send_notification

Sends a desktop notification with a title, message, and optional settings such as play_sound, icon, and app_id. Returns a queued notification response and delivers the notification asynchronously.