# 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)

```bash
npm install -g mcp-notify
```

### Option 2: Clone from GitHub

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

## Configuration

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

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

Or if installed locally:

```json
{
  "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:

| Sound | Description |
|-------|-------------|
| Blow | Default notification sound |
| Basso | Deep, attention-grabbing |
| Bottle | Soft pop |
| Frog | Quirky ribbit |
| Funk | Funky alert |
| Glass | Crystal clear ding |
| Hero | Triumphant fanfare |
| Morse | Dot-dash beep |
| Ping | Simple ping |
| Pop | Quick pop |
| Purr | Gentle purr |
| Sosumi | Classic Mac sound |
| Submarine | Sonar ping |
| Tink | Light tap |

## 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`:

```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](LICENSE) file.

## Contributing

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

## Author

Created for use with [Claude Code](https://claude.ai/claude-code).