{
  "markdown": "# mcp-notifications\n\n[![npm version](https://img.shields.io/npm/v/@topvisor/mcp-notifications.svg)](https://www.npmjs.com/package/@topvisor/mcp-notifications)\n\n🚀 **Ship faster. Miss nothing.**\n\n`mcp-notifications` lets your MCP agent send desktop notifications for completed tasks, failures, and important updates.\n\nThis is especially useful for console AI agents, because they usually have no built-in notifications by default.\n\nNo more checking chats every minute.  \nNo more silent agent responses.  \nJust visible, reliable feedback on your desktop. 🔔\n\n## Common problem this solves\n\nYou give tasks to several AI agents, then wait and keep checking who already replied.\n\nWith `mcp-notifications`, this gets simpler: the agent can notify you on desktop when it needs your input or when work\nis done.\n\n## Why teams install this\n\n- ⚡ Immediate feedback from your MCP workflows.\n- 🧠 Better focus: let the agent work while you stay on your main task.\n- 🖥️ Native OS notifications via `node-notifier`.\n- 🧵 Non-blocking behavior: notification sending is queued in background.\n\n## Install globally\n\nRequirements:\n\n- Node.js `>=20`\n- npm `>=10`\n\n```bash\nnpm i -g @topvisor/mcp-notifications\n```\n\nExecutable name (use this in MCP config):\n\n```bash\nmcp-notifications\n```\n\n`mcp-notifications` is an MCP server entrypoint (`stdio`), not a one-shot notification command.\n\n## Setup: Codex\n\nAdd this to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.notifications]\nenabled = true\ncommand = \"mcp-notifications\"\nargs = []\n```\n\nRestart Codex after config update.\n\n## Setup: Claude Agent\n\nAdd MCP server config to your Claude client config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"notifications\": {\n      \"command\": \"mcp-notifications\",\n      \"args\": []\n    }\n  }\n}\n```\n\nThen restart Claude client.\n\n## AI Agent Notification Instructions\n\nThere are two approaches to notifications: manual and automatic.\n\nChoose the one that works better for your workflow.\n\n### Manual\n\nIn a task where you want to be notified, explicitly ask the agent. Example:\n\n```text\nCount files in the project; after the task is fully complete, notify me with sound.\n```\n\nYou can also define sound, topic, and frequency rules inside a specific chat. Example:\n\n```text\nNotify me about your replies without sound, include the reply text, and use title: \"Large Refactoring\"\n```\n\n### Automatic\n\nAutomatic notifications can be configured globally or per project.\n\nExample instruction to enable automatic notifications for agent replies:\n\n```text\nSend `send_notification` after your replies (actual task time >5 seconds or many steps); `play_sound: false`; `app_id: '{put your chat name here}'`\n```\n\nTime is a rough threshold and depends on model behavior, so adjust this instruction to your own preferences.\n\n### In Skills\n\nYou can also enable notifications in specific skills. Example for a Review skill:\n\n```text\nAfter the review, run `send_notification` with a short summary; `play_sound: true`; `app_id: 'Reviewer {put task id here}'`\n```\n\n## Tool\n\n### `send_notification`\n\nInput:\n\n- `title` `string` (required)\n- `message` `string` (required)\n- `play_sound` `boolean` (optional, default: `false`)\n- `icon` `string` (optional, absolute or relative path to image file)\n- `app_id` `string` (optional, Windows App User Model ID for toast source)\n\nExample:\n\n```json\n{\n  \"title\": \"Codex\",\n  \"message\": \"Deployment completed successfully\",\n  \"play_sound\": true,\n  \"icon\": \"/opt/mcp-notifications/icons/custom.png\",\n  \"app_id\": \"Topvisor.Codex\"\n}\n```\n\n## app_id (Windows)\n\n- `app_id` controls the source shown in Windows toast notifications.\n- If `app_id` is not set, Windows may show `SnoreToast` as the source.\n- You can pass `app_id` in each tool call, or set `MCP_NOTIFICATIONS_APP_ID` as an environment variable for the server.\n\n## Backend selection\n\nYou can select notification transport via env `MCP_NOTIFICATIONS_BACKEND`:\n\n- `auto` (default): uses `powershell` in WSL if available, otherwise `node-notifier`\n- `powershell`: force `powershell.exe` Windows toast transport (recommended for WSL)\n- `node-notifier`: force `node-notifier` package\n\n## Chat Prompts To Test In Codex\n\nUse these messages directly in chat:\n\n```text\nCheck send_notification\n```\n\n```text\nSend a notification without sound: title \"Test\", message \"Check\"\n```\n\n```text\nSend a notification with sound: title \"Test\", message \"Check\"\n```\n\n```text\nSend a notification with app_id \"Topvisor.Codex\": title \"Test\", message \"Check\"\n```\n\n```text\nSend 3 test notifications in a row without sound\n```\n\nExpected tool result in logs/response:\n\n```text\nNotification queued\n```\n\n## Behavior\n\n- ✅ Uses standard system notification channels.\n- 🔊 Uses the standard system notification sound when `play_sound: true`.\n- 🤖 Uses bundled Topvisor robot image as default notification icon.\n- 🧰 Returns quickly while notifications are delivered in background queue.\n\n## Example \n\nThe AI agent is waiting for you:\n\n![example.png](./assets/example.png)\n",
  "bytes": 4956,
  "sha": "da3a1dc34fc411496fb571e33894ec776a91bcb8fa3a7c2d3189cd2995dd9f52",
  "repo_slug": "artemeey/mcp-notifications",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_topvisor_mcp_notifications_94dec40a/readme"
}