MCP Notify

A Model Context Protocol (MCP) server that provides sound alerts, voice messages, and macOS notifications for Claude Code and other MCP-compatible AI assistants.

Get notified when Claude needs your attention - perfect for long-running tasks, when you step away, or when Claude hits a blocker.

Features

• Sound alerts - Play native macOS system sounds

• Voice messages - Text-to-speech using macOS voices

• Desktop notifications - Native macOS notification center

• Zero external dependencies - Uses only built-in macOS tools

Requirements

• macOS (uses native afplay, say, and osascript)

• Node.js 18+

• Claude Code CLI or any MCP-compatible client

Installation

Option 1: Install from npm (recommended)

npm install -g mcp-notify

Option 2: Clone from GitHub

git clone https://github.com/dbreugne/mcp-notify.git
cd mcp-notify
npm install

Configuration

Add to your Claude Code configuration (~/.claude.json):

{
  "mcpServers": {
    "mcp-notify": {
      "command": "npx",
      "args": ["-y", "mcp-notify"]
    }
  }
}

Or if installed locally:

{
  "mcpServers": {
    "mcp-notify": {
      "command": "node",
      "args": ["/path/to/mcp-notify/index.js"]
    }
  }
}

After adding, restart Claude Code for the changes to take effect.

Tools

play_sound

Play a system sound. Great for simple audio alerts.

Parameters:

• sound (optional): Sound name from /System/Library/Sounds/. Default: Blow

Example usage in Claude:

"Play a sound when you're done"

speak_to_user

Speak a message aloud without showing a notification.

Parameters:

• message (required): The message to speak

• voice (optional): macOS voice to use. Default: Samantha

Example usage in Claude:

"Tell me out loud when the build is complete"

notify_user

Full notification with sound, desktop notification, and optional voice.

Parameters:

• message (required): The message to display and optionally speak

• title (optional): Notification title. Default: Claude needs you

• urgency (optional): normal or urgent. Urgent plays sound twice

• voice (optional): Set to true to also speak the message

Example usage in Claude:

"Notify me when you need my input"

Available Sounds

These sounds are available on all macOS systems:

Available Voices

Run say -v ? in Terminal to see all available voices on your system. Common ones:

• Samantha (default) - American English female

• Alex - American English male

• Victoria - American English female

• Daniel - British English male

• Karen - Australian English female

Tips

Best sound for "your turn" notifications

Through testing, Glass works well as a non-intrusive "your turn" notification sound.

Use with hooks

You can also set up a Claude Code hook to automatically play a sound when Claude finishes:

Add to ~/.claude/settings.local.json:

{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "afplay /System/Library/Sounds/Glass.aiff"
      }
    ]
  }
}

Troubleshooting

Sound not playing

1. Check your system volume

2. Ensure the sound file exists: ls /System/Library/Sounds/

3. Test manually: afplay /System/Library/Sounds/Glass.aiff

Notifications not showing

1. Check System Preferences > Notifications

2. Ensure Terminal/your IDE has notification permissions

Voice not working

1. Test manually: say "Hello"

2. Check available voices: say -v ?

License

MIT License - see LICENSE file.

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

Author

Created for use with Claude Code.