Which integrations are available for this server?

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.

How do I use notify-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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.

notify-mcp

by zakotoys

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

@zakotoys/notify-mcp

npm codecov License: MIT

English | 简体中文 | 日本語

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-mcp

Then 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@latest

Call notify_list_audio first, then try notify_desktop or notify.

MCP tools

Tool	Purpose
`notify_list_audio`	List the fixed built-in audio catalog.
`notify_play_audio`	Play one built-in audio track.
`notify_desktop`	Show a native desktop notification.
`notify`	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: afplay for sound and Notification Center through node-notifier.
Windows: PowerShell Media.SoundPlayer for sound and Windows notification center through node-notifier.
Linux: ALSA aplay for sound, with the notification backend selected by node-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-run

The 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 main

Configure 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 tools

notifyNotify with optional audioB

Play an optional built-in audio track and show a desktop notification.

ParametersJSON Schema

Name	Required	Description	Default
`audio`	No
`title`	Yes
`message`	Yes
`subtitle`	No

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of explaining behavior. It discloses the two side effects (audio playback and desktop notification) and notes that audio is optional, but it does not describe return behavior, failure modes, or whether optional audio affects execution when omitted. The core behavior is clear, though not deeply specified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one clear, front-loaded sentence with no filler. Every word contributes to conveying the action and the optional nature of the audio component.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has four parameters, no annotations, and no output schema, yet the description only summarizes the action. It omits parameter semantics, when to choose this over sibling tools, and behavioral expectations beyond the basic side effects, leaving the agent under-informed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only adds meaning for the audio parameter ('optional' and 'built-in'). It does not clarify title, message, or subtitle, and the enum value 'zako' is left unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific behavior: play an optional built-in audio track and show a desktop notification. This clearly identifies the tool as the combined variant, unlike siblings notify_play_audio and notify_desktop, and removes ambiguity about what 'notify' does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance about when to use this tool versus the sibling tools. The description does not mention alternatives such as notify_desktop for notification-only use or notify_play_audio for audio-only use, leaving the agent to infer the routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notify_desktopShow desktop notificationC

Show a native Windows or macOS desktop notification.

ParametersJSON Schema

Name	Required	Description	Default
`title`	Yes
`message`	Yes
`subtitle`	No

TDQS

C2.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does supply some useful context: the notification is 'native' and limited to Windows or macOS, implying platform-specific behavior. It does not disclose side effects, permissions, failure modes, or whether the call blocks, but the core behavior is accurately and plainly stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no filler, and the key behavior is front-loaded. It is appropriately sized for a simple tool, though the brevity contributes to missing usage and parameter details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and zero parameter descriptions, the definition is not complete enough. It lacks guidance on choosing this tool over the generic 'notify' sibling, does not explain the optional 'subtitle' parameter, and provides no context about expected behavior or platform limitations beyond the OS mention.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description adds no explicit parameter-level meaning. The parameter names 'title' and 'message' are fairly self-explanatory in the context of a desktop notification, but 'subtitle' remains ambiguous, and the description does not clarify how it is used on Windows versus macOS. Some indirect value comes from the domain framing, but it does not compensate for the fully undocumented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Show a native Windows or macOS desktop notification.' It clearly identifies what the tool does and is naturally differentiated from the audio-focused siblings by the word 'desktop.' However, it does not explicitly distinguish itself from the generic 'notify' sibling, so it falls just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use this tool versus alternatives. The description does not mention the generic 'notify' sibling or the audio notification tools, nor does it state any exclusions or preferred use cases. An agent would have to infer the selection criteria from the tool name and sibling list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notify_list_audioList built-in audioA

List the fixed audio tracks available to notify-mcp.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description carries the full burden. 'List' implies a read-only operation with no side effects, and 'fixed' indicates the set is predetermined. Still, it does not disclose details such as the exact format of the output or whether any state is involved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no wasted words. The core action and scope are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter list operation with no output schema and no annotations, the description is nearly sufficient. It could be slightly richer by indicating that the returned track identifiers can be used with notify_play_audio, but this is inferable from the sibling tool names.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema already covers everything with 100% coverage, so the description does not need to explain parameters. The term 'fixed audio tracks' adds a small amount of domain context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('List') and a specific resource ('fixed audio tracks available to notify-mcp'). It clearly differentiates from siblings like notify_play_audio by indicating this is an enumeration, not a playback action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is reasonably implied: this lists audio tracks available to notify-mcp, presumably for use with notify_play_audio. However, it never explicitly says 'use this before playing audio' or mentions when not to use it versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notify_play_audioPlay built-in audioA

Play one fixed, built-in audio track on this computer.

ParametersJSON Schema

Name	Required	Description	Default
`audio`	Yes

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It clearly says the action plays a local fixed audio track, but it does not disclose whether playback blocks, how long the sound lasts, or whether it interrupts other audio. That is a moderate gap for a side-effect-producing tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no wasted words. It communicates the core action, the resource, and the scope efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a trivial single-parameter tool with a one-value enum, the description plus schema provide enough to invoke correctly: pass audio='zako'. However, it omits any detail about return behavior or side effects and does not connect to sibling listing tools, so it is complete only because the operation is minimal.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description never mentions the 'audio' parameter. The phrase 'one fixed... track' weakly implies that the enum value 'zako' is the only preset available, but the description adds almost no semantic meaning beyond the schema's enum.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Play'), a resource ('fixed, built-in audio track'), and scope ('on this computer'). The explicit 'one fixed' characteristic distinguishes it from siblings like notify_list_audio, which likely enumerate available tracks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit when-to-use or when-not-to-use guidance. 'One fixed... track' implies this is for the single built-in audio option and not for selecting among multiple tracks, but it never names alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv0.1.2Aug 29, 2026
- First observednotify
- First observednotify_desktop
- First observednotify_list_audio
- First observednotify_play_audio

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored 2026-08-29 18:35 across 4 tools

Disambiguation2/5

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.

Naming Consistency2/5

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.

Tool Count4/5

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.

Completeness4/5

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

ActivityMaintained

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

mcp-serverOAuth
net.vybit
Push notifications with personalized sounds - manage and trigger your vybits via MCP
App Automation Communication
2
VoiceLabsOAuth
now.voicelabs
AI voice generation: text-to-speech and voice cloning from any MCP client.
Text-to-Speech Speech Processing Audio Processing
1
Wubble C
ai.wubble
Create, inspect, and manage Wubble music, speech, voice, and sound-effect requests through MCP.
Audio Processing Speech Processing
332
Texttospeech Mcp C
io.github.varvararatta
MCP server for Text-to-Speech
Text-to-Speech Speech Processing Audio Processing
2

Related MCP Servers

MCP Notifications Server
OS Automation App Automation
konstzv
F
license
B
quality
D
maintenance
Enables Claude and other MCP clients to display native macOS notifications with customizable titles, messages, icons, and sounds through the macOS Notification Center.
Updated 9 months ago (2025-12-19 00:45 UTC)
1
6 npm
-
AI Notify MCP
Developer Tools App Automation
zhiyingzzhou
F
license
C
quality
D
maintenance
Sends 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.
Updated a year ago (2025-07-01 08:12 UTC)
2
-
mcp-notifications
Developer Tools
Artemeey
A
license
D
quality
D
maintenance
Enables MCP agents to send desktop notifications for completed tasks, failures, and important updates, providing visible and reliable feedback.
Updated 4 months ago (2026-05-17 18:12 UTC)
1
33 npm
2
Apache 2.0
apple-notifier-mcp
OS Automation Command Line Speech Processing
piatra-automation
A
license
Not graded
quality
D
maintenance
Enhanced MCP server for sending native macOS notifications with terminal-notifier, interactive dialogs, text-to-speech, screenshots, and file selection.
Updated a year ago (2025-07-01 13:01 UTC)
8 npm
1
MIT