voice-mcp - Voice Mode for Claude Code
A Model Context Protocol (MCP) server that enables voice interactions with Claude and other LLMs. Requires only an OpenAI API key and microphone/speakers.
โจ 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
Setup for Claude Code:
claude mcp add --scope user voice-mcp uvx voice-mcp
export OPENAI_API_KEY=your-openai-key
claude
Try: "Can you ask me a question using voice?"
Example Usage
Once configured, try these prompts with Claude:
"Can you ask me a question using voice and let me respond by speaking?"
"Please read this text aloud to me: [your text here]"
"Listen to what I'm saying for the next 10 seconds"
"Have a voice conversation with me - ask me about my day"
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": {
"voice-mcp": {
"command": "uvx",
"args": ["voice-mcp"],
"env": {
"OPENAI_API_KEY": "your-openai-key"
}
}
}
}
Using Docker/Podman
{
"mcpServers": {
"voice-mcp": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--device", "/dev/snd",
"-e", "PULSE_RUNTIME_PATH=/run/user/1000/pulse",
"-v", "/run/user/1000/pulse:/run/user/1000/pulse",
"ghcr.io/mbailey/voice-mcp:latest"
],
"env": {
"OPENAI_API_KEY": "your-openai-key"
}
}
}
}
Using pip install
{
"mcpServers": {
"voice-mcp": {
"command": "voice-mcp",
"env": {
"OPENAI_API_KEY": "your-openai-key"
}
}
}
}
Tools
Tool | Description |
---|---|
ask_voice_question |
Ask a question via voice, get spoken response |
speak_text |
Convert text to speech |
listen_for_speech |
Record and transcribe speech |
check_room_status |
Show LiveKit room status |
check_audio_devices |
List audio devices |
Configuration
Required
export OPENAI_API_KEY="your-key"
Optional
# Custom 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="af_sky" # Sky Voice (Kokoro)
export TTS_MODEL="tts-1"
export STT_MODEL="whisper-1"
# LiveKit (for room-based communication)
export LIVEKIT_URL="wss://your-app.livekit.cloud"
export LIVEKIT_API_KEY="your-api-key"
export LIVEKIT_API_SECRET="your-api-secret"
# Debug
export VOICE_MCP_DEBUG="true"
Troubleshooting
- No microphone: Check system permissions
- UV not found:
curl -LsSf https://astral.sh/uv/install.sh | sh
- API errors: Verify
OPENAI_API_KEY
- Debug mode: Set
VOICE_MCP_DEBUG=true
(saves audio to~/voice-mcp_recordings/
)
License
MIT