What is Voicemode

Voice Mode is a tool designed to facilitate natural voice conversations for AI assistants like Claude and ChatGPT. It achieves this through the Model Context Protocol (MCP), enabling users to engage in real-time voice interactions powered by speech-to-text (STT) and text-to-speech (TTS) services.

Use cases

Voice Mode can be used for various applications including interactive voice conversations, virtual assistants, user engagement in games, and accessibility tools. It supports diverse scenarios like personalized interaction with AI, hands-free device control, and voice-enabled customer support.

How to use

To get started with Voice Mode, users need to install it via their preferred method (e.g., with Claude or pip), set up their OpenAI API key, and then run the application to initiate voice interactions. Users can issue commands like “Let’s have a voice conversation” to start engaging with the AI.

Key features

Key features of Voice Mode include real-time low-latency voice interactions, support for multiple audio transports (local microphone or LiveKit), seamless integration with any STT/TTS service, and tools for managing audio devices and room status in LiveKit. It also allows hands-free operation with automatic response waiting.

Where to use

Voice Mode can be used on various platforms and operating systems including Linux, macOS, and Windows. It operates in environments that support the Model Context Protocol and is suitable for personal devices, cloud applications, and integrated systems where voice interaction is beneficial.

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:

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.

Installation

Prerequisites

• Python >= 3.10
• Astral UV - Package manager (install with curl -LsSf https://astral.sh/uv/install.sh | sh)
• OpenAI API Key (or compatible service)

System Dependencies

sudo apt install python3-dev libasound2-dev libportaudio2 portaudio19-dev ffmpeg

sudo dnf install python3-devel alsa-lib-devel portaudio-devel ffmpeg

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install portaudio ffmpeg

Quick Install

# Using Claude Code (recommended)
claude mcp add --scope user voice-mode uvx voice-mode

# Using UV
uvx voice-mode

# Using pip
pip install voice-mode

Manual Configuration for Different Clients

claude mcp add voice-mode -- uvx voice-mode

claude mcp add voice-mode --env OPENAI_API_KEY=your-openai-key -- uvx voice-mode

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": [
        "voice-mode"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

{
  "mcpServers": {
    "voice-mode": {
      "command": "cmd",
      "args": [
        "/c",
        "uvx",
        "voice-mode"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": [
        "voice-mode"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": [
            "voice-mode"
          ],
          "env": {
            "OPENAI_API_KEY": "your-openai-key"
          }
        }
      }
    ]
  }
}

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": [
        "voice-mode"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": [
        "voice-mode"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": [
        "voice-mode"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

{
  "context_servers": {
    "voice-mode": {
      "command": {
        "path": "uvx",
        "args": [
          "voice-mode"
        ],
        "env": {
          "OPENAI_API_KEY": "your-openai-key"
        }
      }
    }
  }
}

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": [
        "voice-mode"
      ],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

Alternative Installation Options

docker run -it --rm \
  -e OPENAI_API_KEY=your-openai-key \
  --device /dev/snd \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -e DISPLAY=$DISPLAY \
  ghcr.io/mbailey/voicemode:latest

pipx install voice-mode

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

Tools

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 VOICEMODE_DEBUG="true"

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

# Audio format configuration (default: pcm)
export VOICEMODE_AUDIO_FORMAT="pcm"         # Options: pcm, mp3, wav, flac, aac, opus
export VOICEMODE_TTS_AUDIO_FORMAT="pcm"     # Override for TTS only (default: pcm)
export VOICEMODE_STT_AUDIO_FORMAT="mp3"     # Override for STT upload

# Format-specific quality settings
export VOICEMODE_OPUS_BITRATE="32000"       # Opus bitrate (default: 32kbps)
export VOICEMODE_MP3_BITRATE="64k"          # MP3 bitrate (default: 64k)

Audio Format Configuration

Voice Mode uses PCM audio format by default for TTS streaming for optimal real-time performance:

• PCM (default for TTS): Zero latency, best streaming performance, uncompressed
• MP3: Wide compatibility, good compression for uploads
• WAV: Uncompressed, good for local processing
• FLAC: Lossless compression, good for archival
• AAC: Good compression, Apple ecosystem
• Opus: Small files but NOT recommended for streaming (quality issues)

The audio format is automatically validated against provider capabilities and will fallback to a supported format if needed.

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
  • WSL2 Users: See WSL2 Microphone Access Guide
• 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 VOICEMODE_DEBUG=true

Debug audio files are saved to: ~/voicemode_recordings/

Audio Diagnostics

Run the diagnostic script to check your audio setup:

python scripts/diagnose-wsl-audio.py

This will check for required packages, audio services, and provide specific recommendations.

Audio Saving

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

export VOICEMODE_SAVE_AUDIO=true

Audio files are saved to: ~/voicemode_audio/ with timestamps in the filename.

Documentation

• Configuration Guide - Complete setup instructions for all MCP hosts
• Using uv/uvx - Package management with uv and uvx
• Local Development - Development setup guide
• Audio Formats - Audio format configuration and migration
• Statistics Dashboard - Performance monitoring and metrics

Service Guides

• Whisper.cpp Setup - Local speech-to-text configuration
• Kokoro Setup - Local text-to-speech configuration
• LiveKit Integration - Real-time voice communication

Troubleshooting

• WSL2 Microphone Access - WSL2 audio setup
• Migration Guide - Upgrading from older versions

Links

• Website: getvoicemode.com
• GitHub: github.com/mbailey/voicemode
• PyPI: pypi.org/project/voice-mcp
• npm: npmjs.com/package/voicemode

Community

• Discord: Join our community
• Twitter/X: @getvoicemode
• YouTube: @getvoicemode

License

MIT - A Failmode Project