mbailey

Voice Mode

Community mbailey
Updated

Conversational Coding

Voice Mode

Install via: uvx voice-mode | pip install voice-mode | getvoicemode.com

Natural voice conversations for AI assistants. Voice Mode brings human-like voice interactions to Claude, ChatGPT, and other LLMs through the Model Context Protocol (MCP).

๐Ÿ–ฅ๏ธ Compatibility

Runs on: Linux โ€ข macOS โ€ข Windows (WSL) | Python: 3.10+ | Tested: Ubuntu 24.04 LTS, Fedora 42

โœจ Features

  • ๐ŸŽ™๏ธ Voice conversations with Claude - ask questions and hear responses
  • ๐Ÿ”„ Multiple transports - local microphone or LiveKit room-based communication
  • ๐Ÿ—ฃ๏ธ OpenAI-compatible - works with any STT/TTS service (local or cloud)
  • โšก Real-time - low-latency voice interactions with automatic transport selection
  • ๐Ÿ”ง MCP Integration - seamless with Claude Desktop and other MCP clients

๐ŸŽฏ Simple Requirements

All you need to get started:

  1. ๐Ÿ”‘ OpenAI API Key (or compatible service) - for speech-to-text and text-to-speech
  2. ๐ŸŽค Computer with microphone and speakers OR โ˜๏ธ LiveKit server (LiveKit Cloud or self-hosted)

Quick Start

claude mcp add --scope user voice-mode uvx voice-mode
export OPENAI_API_KEY=your-openai-key
claude
> /converse

๐ŸŽฌ Demo

Watch Voice Mode in action:

Voice Mode Demo

Example Usage

Once configured, try these prompts with Claude:

  • "Let's have a voice conversation"
  • "Ask me about my day using voice"
  • "Tell me a joke" (Claude will speak and wait for your response)
  • "Say goodbye" (Claude will speak without waiting)

The new converse function makes voice interactions more natural - it automatically waits for your response by default.

Claude Desktop Setup

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json

Using uvx (recommended)
{
  "mcpServers": {
    "voicemode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}
Using pip install
{
  "mcpServers": {
    "voicemode": {
      "command": "voicemode",
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

Tools

Tool Description Key Parameters
converse Have a voice conversation - speak and optionally listen message, wait_for_response (default: true), listen_duration (default: 10s), transport (auto/local/livekit)
listen_for_speech Listen for speech and convert to text duration (default: 5s)
check_room_status Check LiveKit room status and participants None
check_audio_devices List available audio input/output devices None
start_kokoro Start the Kokoro TTS service models_dir (optional, defaults to ~/Models/kokoro)
stop_kokoro Stop the Kokoro TTS service None
kokoro_status Check the status of Kokoro TTS service None

Note: The converse tool is the primary interface for voice interactions, combining speaking and listening in a natural flow.

Configuration

๐Ÿ“– See docs/configuration.md for complete setup instructions for all MCP hosts

๐Ÿ“ Ready-to-use config files in config-examples/

Quick Setup

The only required configuration is your OpenAI API key:

export OPENAI_API_KEY="your-key"

Optional Settings

# Custom STT/TTS services (OpenAI-compatible)
export STT_BASE_URL="http://localhost:2022/v1"  # Local Whisper
export TTS_BASE_URL="http://localhost:8880/v1"  # Local TTS
export TTS_VOICE="alloy"                        # Voice selection

# LiveKit (for room-based communication)
# See docs/livekit/ for setup guide
export LIVEKIT_URL="wss://your-app.livekit.cloud"
export LIVEKIT_API_KEY="your-api-key"
export LIVEKIT_API_SECRET="your-api-secret"

# Debug mode
export VOICE_MCP_DEBUG="true"

# Save all audio (TTS output and STT input)
export VOICE_MCP_SAVE_AUDIO="true"

Local STT/TTS Services

For privacy-focused or offline usage, Voice Mode supports local speech services:

  • Whisper.cpp - Local speech-to-text with OpenAI-compatible API
  • Kokoro - Local text-to-speech with multiple voice options

These services provide the same API interface as OpenAI, allowing seamless switching between cloud and local processing.

OpenAI API Compatibility Benefits

By strictly adhering to OpenAI's API standard, Voice Mode enables powerful deployment flexibility:

  • ๐Ÿ”€ Transparent Routing: Users can implement their own API proxies or gateways outside of Voice Mode to route requests to different providers based on custom logic (cost, latency, availability, etc.)
  • ๐ŸŽฏ Model Selection: Deploy routing layers that select optimal models per request without modifying Voice Mode configuration
  • ๐Ÿ’ฐ Cost Optimization: Build intelligent routers that balance between expensive cloud APIs and free local models
  • ๐Ÿ”ง No Lock-in: Switch providers by simply changing the BASE_URL - no code changes required

Example: Simply set OPENAI_BASE_URL to point to your custom router:

export OPENAI_BASE_URL="https://router.example.com/v1"
export OPENAI_API_KEY="your-key"
# Voice Mode now uses your router for all OpenAI API calls

The OpenAI SDK handles this automatically - no Voice Mode configuration needed!

Architecture

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚   Claude/LLM        โ”‚     โ”‚  LiveKit Server  โ”‚     โ”‚  Voice Frontend     โ”‚
โ”‚   (MCP Client)      โ”‚โ—„โ”€โ”€โ”€โ”€โ–บโ”‚  (Optional)     โ”‚โ—„โ”€โ”€โ”€โ–บโ”‚  (Optional)         โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜     โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜     โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
         โ”‚                            โ”‚
         โ”‚                            โ”‚
         โ–ผ                            โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  Voice MCP Server   โ”‚     โ”‚   Audio Services โ”‚
โ”‚  โ€ข converse         โ”‚     โ”‚  โ€ข OpenAI APIs   โ”‚
โ”‚  โ€ข listen_for_speechโ”‚โ—„โ”€โ”€โ”€โ–บโ”‚  โ€ข Local Whisper โ”‚
โ”‚  โ€ข check_room_statusโ”‚     โ”‚  โ€ข Local TTS     โ”‚
โ”‚  โ€ข check_audio_devices    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Troubleshooting

Common Issues

  • No microphone access: Check system permissions for terminal/application
  • UV not found: Install with curl -LsSf https://astral.sh/uv/install.sh | sh
  • OpenAI API error: Verify your OPENAI_API_KEY is set correctly
  • No audio output: Check system audio settings and available devices

Debug Mode

Enable detailed logging and audio file saving:

export VOICE_MCP_DEBUG=true

Debug audio files are saved to: ~/voice-mcp_recordings/

Audio Saving

To save all audio files (both TTS output and STT input):

export VOICE_MCP_SAVE_AUDIO=true

Audio files are saved to: ~/voice-mcp_audio/ with timestamps in the filename.

Links

License

MIT - A Failmode Project

MCP Server ยท Populars

MCP Server ยท New