Skip to main content
Glama
notify-mcp

notify-mcp

by zakotoys

@zakotoys/notify-mcp

npm CI 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.

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

    B3.2/5.0

    Scored 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

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      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.
      1
      MIT
    • A
      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.
      2
      MIT
    • 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.
      1
      54 npm
      2
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      A lightweight MCP server that enables sending native desktop notifications with action buttons and text replies, compatible with any MCP client.
      1
      29 npm
      1
      MIT