VoiceMode MCP Server for Claude Voice Conversations

Overview

VoiceMode is an MCP (Model Context Protocol) server that enables natural voice conversations with Claude (including Claude Code) by providing an OpenAI-compatible STT/TTS interface. It acts as a bridge between Claude (or any MCP-capable agent) and speech services — locally hosted engines (Whisper.cpp for ASR, Kokoro for TTS) or cloud providers following OpenAI-compatible APIs — so you can speak to and hear responses from Claude with low latency and optional local-only privacy.

For developers, VoiceMode simplifies adding voice to a conversational agent: it implements the STT/TTS endpoints Claude expects, handles recording/silence detection, and can fall back to cloud APIs when local models are not available. This is useful when typing is inconvenient (walking, cooking, accessibility scenarios) or when you need quick spoken feedback integrated into development or automation workflows.

Features

• OpenAI-compatible STT/TTS API surface (acts like OpenAI speech endpoints)
• Works with Claude Code and other MCP-capable agents via the MCP server
• Optional local speech services (Whisper.cpp for ASR, Kokoro for TTS)
• Fast response times and low-latency audio streaming
• Smart silence detection to stop recording automatically
• Privacy-first mode: run entirely locally, or use cloud fallbacks
• Save audio for debugging via environment variable
• Cross-platform support: Linux, macOS, Windows (WSL), NixOS
• Python 3.10–3.14 compatible

Installation / Configuration

Quick-start commands for common setups.

1. Claude Code plugin (recommended)

# Add VoiceMode marketplace and install plugin
claude plugin marketplace add mbailey/voicemode
claude plugin install voicemode@voicemode

# Install command-line/local services (runs installer)
# From inside Claude plugin UI or CLI:
voicemode:install

# Start a conversation
voicemode:converse

2. Python installer package (manual / CLI)

# If you need the uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run the installer that sets up dependencies and local voice services
uvx voice-mode-install

# Add VoiceMode to Claude via MCP
claude mcp add --scope user voicemode -- uvx --refresh voice-mode

# Optionally set an OpenAI API key for cloud fallbacks
export OPENAI_API_KEY="your-openai-key"

# Start a conversation through Claude/CLI
claude converse

3. From source

git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .

Configuration

# Edit the VoiceMode configuration (CLI helper)
voicemode config edit

# Enable saving recorded audio for debugging
export VOICEMODE_SAVE_AUDIO=true
# Files stored under: ~/.voicemode/audio/YYYY/MM/

Permissions (optional)

# Add to ~/.claude/settings.json to avoid permission prompts
{
  "permissions": {
    "allow": [
      "mcp__voicemode__converse",
      "mcp__voicemode__service"
    ]
  }
}

System dependencies (examples)

Available Resources

• Repository: https://github.com/mbailey/voicemode
• Website / project: https://getvoicemode.com
• Documentation site: https://voice-mode.readthedocs.io
• PyPI package: https://pypi.org/project/voice-mode/
• Demo video: YouTube (search “VoiceMode Demo”)

Local service guides:

• Whisper (local ASR) setup guide
• Kokoro (local TTS) setup guide

Use Cases

• Hands-free coding/debugging: ask Claude to explain or modify code while you type or read elsewhere.
• Accessibility: provide spoken interaction for users who prefer audio or have limited dexterity.
• On-the-go workflows: get briefings, run quick queries, or debug while walking between meetings.
• Embedded demos: integrate voice into demos or user tests without reimplementing STT/TTS APIs.
• Privacy-first deployments: run ASR/TTS locally behind a private network with optional cloud fallback.

Concrete example — add voice to a Claude conversation:

1. Install VoiceMode and local services.
2. Set OPENAI_API_KEY if you want cloud fallbacks.
3. Run the MCP server through the Claude plugin or the local CLI.
4. Start a conversation and speak; VoiceMode will record, transcribe, send text to Claude, and play TTS responses.

Troubleshooting / Tips

• No microphone: verify OS/app permissions, and on WSL2 install pulseaudio packages.
• No audio out: check system audio devices and default sink settings.
• UV not found: install via curl command shown above.
• OpenAI API errors: confirm OPENAI_API_KEY is set and valid.
• Debugging audio: set VOICEMODE_SAVE_AUDIO=true to save recordings for inspection.

For full setup, advanced configuration, and contribution guidelines, see the repository documentation at the GitHub link above.