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:
- ๐ OpenAI API Key (or compatible service) - for speech-to-text and text-to-speech
- ๐ค 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:
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.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"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
- Website: getvoicemode.com
- GitHub: github.com/mbailey/voicemode
- PyPI: pypi.org/project/voice-mcp
- npm: npmjs.com/package/voicemode
License
MIT - A Failmode Project