Voice MCP

VoiceMode

> Install via: uv tool install voice-mode | getvoicemode.com

Natural voice conversations for AI assistants. VoiceMode brings human-like voice interactions to Claude Code, AI code editors through the Model Context Protocol (MCP).

🖥️ Compatibility

Runs on: Linux • macOS • Windows (WSL) • NixOS | Python: 3.10+

✨ Features

🎙️ Natural Voice Conversations with Claude Code - ask questions and hear responses
🗣️ Supports local Voice Models - works with any OpenAI API compatible STT/TTS services
⚡ Real-time - low-latency voice interactions with automatic transport selection
🔧 MCP Integration - seamless with Claude Code (and other MCP clients)
🎯 Silence detection - automatically stops recording when you stop speaking (no more waiting!)
🔄 Multiple transports - local microphone or LiveKit room-based communication

🎯 Simple Requirements

All you need to get started:

🎤 Computer with microphone and speakers
🔑 OpenAI API Key (Recommended, if only as a backup for local services)

Quick Start

Automatic Installation (Recommended)

Install Claude Code with VoiceMode configured and ready to run on Linux, macOS, and Windows WSL:

# Download and run the installer
curl -O https://getvoicemode.com/install.sh &amp;&amp; bash install.sh

# While local voice services can be installed automatically, we recommend
# providing an OpenAI API key as a fallback in case local services are unavailable
export OPENAI_API_KEY=your-openai-key  # Optional but recommended

# Start a voice conversation
claude converse

This installer will:

Install all system dependencies (Node.js, audio libraries, etc.)
Install Claude Code if not already installed
Configure VoiceMode as an MCP server
Set up your system for voice conversations

Manual Installation

For manual setup steps, see the Getting Started Guide.

🎬 Demo

Watch VoiceMode in action with Claude Code:

The converse function makes voice interactions natural - it automatically waits for your response by default, creating a real conversation flow.

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

Ubuntu/Debian

sudo apt update
sudo apt install -y ffmpeg libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev

Note for WSL2 users: WSL2 requires additional audio packages (pulseaudio, libasound2-plugins) for microphone access.

Fedora/RHEL

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

macOS

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

# Install dependencies
brew install ffmpeg node portaudio

Windows (WSL)

Follow the Ubuntu/Debian instructions above within WSL.

NixOS

VoiceMode includes a flake.nix with all required dependencies. You can either:

Use the development shell (temporary):

nix develop github:mbailey/voicemode

Install system-wide (see Installation section below)

Quick Install

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

Configuration for AI Coding Assistants

> 📖 Looking for detailed setup instructions? Check our comprehensive Getting Started Guide for step-by-step instructions!

Below are quick configuration snippets. For full installation and setup instructions, see the integration guides above.

Claude Code (CLI)

claude mcp add --scope user voicemode -- uvx --refresh voice-mode

Or with environment variables:

claude mcp add --scope user --env OPENAI_API_KEY=your-openai-key voicemode -- uvx --refresh voice-mode

Alternative Installation Options

From source

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

NixOS Installation Options

1. Install with nix profile (user-wide):

nix profile install github:mbailey/voicemode

2. Add to NixOS configuration (system-wide):

# In /etc/nixos/configuration.nix
environment.systemPackages = [
  (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];

3. Add to home-manager:

# In home-manager configuration
home.packages = [
  (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];

4. Run without installing:

nix run github:mbailey/voicemode

Configuration

📖 Getting Started - Step-by-step setup guide
🔧 Configuration Reference - All environment variables

Quick Setup

The only required configuration is your OpenAI API key:

export OPENAI_API_KEY="your-key"

Local STT/TTS Services

For privacy-focused or offline usage, VoiceMode 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.

Troubleshooting

Common Issues

No microphone access: Check system permissions for terminal/application
- WSL2 Users: Additional audio packages (pulseaudio, libasound2-plugins) required for microphone access
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

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/YYYY/MM/ with timestamps in the filename.

Documentation

📚 Read the full documentation at voice-mode.readthedocs.io

Getting Started

Getting Started - Step-by-step setup for all supported tools
Configuration Guide - Complete environment variable reference

Development

Development Setup - Local development guide

Service Guides

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

License

MIT - A Failmode Project

mcp-name: com.failmode/voicemode