Voice Notification

You can use the MCP Voice Notification server to hear spoken alerts when Claude Code finishes a task. It connects to Grok’s voice API to deliver real-time audio alerts, and you can run it locally or expose it over HTTP for shared use.

How to use

Set up and run the server, then configure your MCP client to call the voice notification endpoint when you want an audio alert. You can run the server locally for personal use or expose it via HTTP so other colleagues or tools can trigger alerts.

There are two connection options you can choose from. The HTTP option lets you run a persistent service that others can reach at a URL. The stdio option runs a local process that communicates via standard input and output with your MCP client. Pick the method that matches your setup and security needs.

How to install

Prerequisites you need before installation:

• uv (Python package manager)
• A Grok API key from x.ai
• Audio playback capability on your system (afplay on macOS, aplay or paplay on Linux)

Step-by-step installation commands:

git clone https://github.com/orishu/mcp-voice-notif.git
cd mcp-voice-notif
uv sync
cp env.sample .env
# Edit .env and add your GROK_API_KEY

Configuration and starting modes

Choose your preferred server mode and use the corresponding startup commands. The following examples assume you will replace /path/to/mcp-voice-notif with the actual path to your project directory.

# Option 1: Stdio Server (local)
uv run --directory /path/to/mcp-voice-notif python stdio_server.py

# Option 2: HTTP Server (remote/shared)
uv run python server.py

Two MCP server configurations

Use the following MCP server configurations exactly as shown to connect your clients. The HTTP config exposes a remote endpoint, while the stdio config runs locally and expects an environment variable for authentication.

# HTTP (remote/shared) server config
{
  "type": "http",
  "name": "voice_notification_http",
  "url": "http://127.0.0.1:8000/mcp",
  "args": []
}

# STDIO (local) server config
{
  "type": "stdio",
  "name": "voice_notification_stdio",
  "command": "uv",
  "args": ["run", "--directory", "/path/to/mcp-voice-notif", "python", "stdio_server.py"],
  "env": {
    "GROK_API_KEY": "YOUR_API_KEY"
  }
}

Available tools

voice_notification

Generates and plays a voice notification using Grok's realtime voice API.