MCP Voice Notification

An MCP server that provides voice notifications using the Grok Voice API. 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 (Python package manager)
• A Grok API key from x.ai
• Audio playback capability (afplay on macOS, aplay/paplay on Linux)

Installation

1. Clone the repository:

   git clone https://github.com/orishu/mcp-voice-notif.git
   cd mcp-voice-notif
   

2. Install dependencies with uv:

   uv sync
   

3. Set up your environment:

   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:

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

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

   uv run python server.py
   

   The server will start on http://127.0.0.1:8000.

2. Add to your Claude Code MCP configuration:

   {
     "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):

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:

uv run python test_voice_api.py

License

MIT License - see LICENSE for details.