# MCP Voice Notification

An MCP server that provides voice notifications using the [Grok Voice API](https://x.ai). Perfect for alerting you when Claude Code has finished a task.

## Features

- Text-to-speech voice notifications via Grok's realtime voice API
- Works with Claude Code and other MCP-compatible clients
- Two server modes: HTTP (streamable) or stdio (local)
- Cross-platform audio playback (macOS, Linux)

## Prerequisites

- [uv](https://docs.astral.sh/uv/) (Python package manager)
- A Grok API key from [x.ai](https://x.ai)
- Audio playback capability (`afplay` on macOS, `aplay`/`paplay` on Linux)

## Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/orishu/mcp-voice-notif.git
   cd mcp-voice-notif
   ```

2. Install dependencies with uv:
   ```bash
   uv sync
   ```

3. Set up your environment:
   ```bash
   cp env.sample .env
   # Edit .env and add your GROK_API_KEY
   ```

## Usage

### Option 1: Stdio Server (Recommended for local use)

The stdio server communicates via standard input/output, which is the simplest setup for local MCP clients.

#### Using the `claude mcp add` command (Recommended)

The easiest way to add the server is using the Claude Code CLI:

```bash
claude mcp add voice-notification -e GROK_API_KEY=your_api_key_here -- \
  uv run --directory /path/to/mcp-voice-notif python stdio_server.py
```

Replace `/path/to/mcp-voice-notif` with the actual path to this project.

#### Manual configuration

Alternatively, add to your Claude Code MCP configuration (`~/.claude/claude_code_config.json`):

```json
{
  "mcpServers": {
    "voice-notification": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-voice-notif", "python", "stdio_server.py"],
      "env": {
        "GROK_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Option 2: HTTP Server (For remote/shared use)

The HTTP server runs as a persistent service, useful for remote access or shared setups.

1. Start the server:
   ```bash
   uv run python server.py
   ```
   The server will start on `http://127.0.0.1:8000`.

2. Add to your Claude Code MCP configuration:
   ```json
   {
     "mcpServers": {
       "voice-notification": {
         "type": "streamable-http",
         "url": "http://127.0.0.1:8000/mcp"
       }
     }
   }
   ```

## Tool Reference

### `voice_notification`

Generates and plays a voice notification.

**Parameters:**
- `text` (string, optional): The text to speak. Default: "Done!"

**Example responses:**
- "Voice notification played: 'Build complete!'"
- "No audio data received from API"

## Configuring Claude Code to Use Voice Notifications

To have Claude Code automatically notify you when it's ready for your next prompt, add the following to your project's `CLAUDE.md` file (or global `~/.claude/CLAUDE.md`):

```markdown
When you complete a task, use the voice_notification tool to alert the user.
Keep the message short and contextual (e.g., "Build done!", "Tests passed!", "Ready!").
```

This instructs the agent to call the voice notification with a brief, task-relevant message whenever it finishes working.

## Testing

To test the voice API directly:

```bash
uv run python test_voice_api.py
```

## License

MIT License - see [LICENSE](LICENSE) for details.