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