notify-mcp
Plays built-in audio through ALSA aplay and shows desktop notifications using the available notification backend.
Sends native desktop notifications to macOS Notification Center and plays built-in audio using afplay.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@notify-mcp play an alert sound and notify me 'Deploy complete'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@zakotoys/notify-mcp
notify-mcp is a small Model Context Protocol
server for playing fixed built-in sounds and showing native desktop
notifications. It connects Claude Desktop, Cursor, OpenCode, Codex, or another
MCP client to the local Windows or macOS notification system through stdio.
Features
Four standard MCP tools for listing the audio, playing it, sending a desktop notification, and doing both in one call.
One built-in audio track:
zako.Native notifications through
node-notifier(Windows notification center and macOS Notification Center).Audio is intentionally closed: callers can select a built-in id, but cannot provide a file path, URL, upload, or runtime-added track.
Business logic is separated from operating-system adapters and is fully testable without a speaker or desktop session.
Related MCP server: AI Notify MCP
Requirements
Node.js 20 or newer.
A supported MCP client such as Claude Desktop, Cursor, OpenCode, or Codex.
Windows 10+ or macOS for the primary desktop notification experience.
Linux is also supported when aplay and a desktop notification backend are
available.
Quick start
Claude Desktop, Cursor, OpenCode, or Codex
Install the package globally:
npm install --global @zakotoys/notify-mcpThen add this server to the client's MCP configuration:
{
"mcpServers": {
"notify": {
"command": "notify-mcp"
}
}
}You can also run the package without a global install:
{
"mcpServers": {
"notify": {
"command": "npx",
"args": ["-y", "@zakotoys/notify-mcp@latest"]
}
}
}For Windows clients that do not resolve npx directly, use cmd:
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@zakotoys/notify-mcp@latest"]
}MCP Inspector
npx @modelcontextprotocol/inspector npx -y @zakotoys/notify-mcp@latestCall notify_list_audio first, then try notify_desktop or notify.
MCP tools
Tool | Purpose |
| List the fixed built-in audio catalog. |
| Play one built-in audio track. |
| Show a native desktop notification. |
| Play optional built-in audio, then show a notification. |
notify_list_audio
Takes no arguments. Each item includes an id, label, description, frequency,
and duration.
notify_play_audio
{ "audio": "zako" }audio must be zako. The server ships a short voice-only WAV asset, delegates
to the native player, and never accepts external audio paths or URLs.
The clip is a short vocal extraction from the source documented in
assets/audio/SOURCE.md. Verify redistribution rights
before publishing a package containing this asset.
notify_desktop
{
"title": "Build complete",
"message": "notify-mcp finished successfully",
"subtitle": "Optional supplementary text"
}title is required and limited to 200 characters. message is required and
limited to 2,000 characters. subtitle is optional and limited to 200
characters.
notify
{
"audio": "zako",
"title": "Reminder",
"message": "The meeting starts in five minutes"
}audio is optional. When provided, playback completes before the desktop
notification is submitted.
Platform behavior
macOS:
afplayfor sound and Notification Center throughnode-notifier.Windows: PowerShell
Media.SoundPlayerfor sound and Windows notification center throughnode-notifier.Linux: ALSA
aplayfor sound, with the notification backend selected bynode-notifier.
The operating system may require permission for the terminal application to send notifications. The server does not upload notification text or audio.
Development
npm install
npm run typecheck # TypeScript checks (including tests)
npm test # Vitest + V8 coverage
npm run build # Compile runtime files into dist/
npm run ci # All checks, coverage, build, and package dry-runThe test suite uses injected fake adapters and an in-memory MCP transport, so CI does not need a speaker, GUI, or real notification center.
Releases
Every vX.Y.Z tag is published by GitHub Actions after the full CI suite and a
package-version check pass. The publish workflow uses npm Trusted Publishing
with provenance and creates a GitHub Release with generated notes.
To release a new version:
npm version patch # or minor / major
git push --follow-tags origin mainConfigure the npm package's Trusted Publisher for the repository
zakotoys/notify-mcp, workflow publish.yml, and the GitHub Actions provider.
Project scope
This project intentionally provides local notification primitives only. It does not manage notification history, remote audio, user-uploaded media, or a background daemon. MCP clients decide when a tool should be called.
License
MIT, see LICENSE.
Available Tools
4 toolsnotifyNotify with optional audioB
Play an optional built-in audio track and show a desktop notification.
Inputs: title (required), message (required), audio, subtitle.
notify_desktopShow desktop notificationC
Show a native Windows or macOS desktop notification.
Inputs: title (required), message (required), subtitle.
notify_list_audioList built-in audioA
List the fixed audio tracks available to notify-mcp.
Inputs: no named parameters.
notify_play_audioPlay built-in audioA
Play one fixed, built-in audio track on this computer.
Inputs: audio (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
notify_desktop and notify both show desktop notifications, and notify_play_audio and notify both play audio. Only notify_list_audio is clearly distinct, so agents may struggle to choose between the combined and single-purpose tools.
Three tools use the notify_ prefix, but bare 'notify' breaks the pattern. Verb usage is inconsistent: 'notify_play_audio' uses an action, while 'notify_desktop' uses a noun, so naming conventions are mixed.
Four tools is a reasonable size for a simple notification and audio player. Each tool serves a distinct need, though notify is a convenience wrapper that partially duplicates the other two.
The surface covers listing audio, playing audio, showing desktop notifications, and combining both. Minor gaps exist such as no stop/volume control or notification customization, but for fixed built-in tracks the core lifecycle is covered.
Maintenance
Related MCP Connectors
Push notifications with personalized sounds - manage and trigger your vybits via MCP
AI voice generation: text-to-speech and voice cloning from any MCP client.
Create, inspect, and manage Wubble music, speech, voice, and sound-effect requests through MCP.
MCP server for Text-to-Speech
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables Claude and other MCP clients to display native macOS notifications with customizable titles, messages, icons, and sounds through the macOS Notification Center.1MIT
- AlicenseCqualityDmaintenanceSends system notifications when AI completes responses in MCP-compatible code editors, with cross-platform support for macOS, Windows, and Linux including customizable titles, messages, icons, and sound effects.2MIT
- AlicenseDqualityDmaintenanceEnables MCP agents to send desktop notifications for completed tasks, failures, and important updates, providing visible and reliable feedback.154 npm2Apache 2.0
- AlicenseAqualityDmaintenanceA lightweight MCP server that enables sending native desktop notifications with action buttons and text replies, compatible with any MCP client.129 npm1MIT