Lets an AI client hold natural voice conversations through speech-to-text and text-to-speech, with local or cloud services.
Also known as mbailey/voicemode, voice-mode
- Stars
- 1,458
- Tools
- —
- Downloads, 30 days
- 16,278
- Latest version
- 9.0.2
- Last commit
- Nov 14, 2026
- License
- MIT
What is VoiceMode MCP?
VoiceMode lets an AI client hold natural voice conversations through speech-to-text and text-to-speech, with local or cloud services.
Summary generated from the project's README
About VoiceMode MCP server
Engaging in spoken dialogue with Claude Code or other MCP-capable agents is possible through VoiceMode. This server enables users to interact with AI using speech-to-text and text-to-speech capabilities, making it useful when hands or eyes are busy, such as during cooking or while walking. It supports multiple platforms including macOS, Linux, Windows via WSL, and NixOS.
Users can choose between cloud-based services or entirely local setups for increased privacy and offline availability. For local operation, the system can utilize Whisper.cpp for speech-to-text and Kokoro for text-to-speech. If cloud services are preferred, providing an OpenAI API key allows the server to use OpenAI as a fallback. The setup is managed via the Claude Code plugin marketplace or through a Python installer using the uv package manager.
What you can do with it
- 1Hands-free debugging sessionsAsk your AI agent to help you debug code while your hands are occupied with other tasks.
- 2Voice-only interaction during movementHold a conversation with Claude Code while walking to a meeting.
- 3Private offline AI conversationsRun your voice interactions locally without sending data to the cloud using Whisper and Kokoro.
- 4Reducing screen time strainInteract with your AI assistant using only your voice to give your eyes a rest.
Written from the project's README. Every use case is checked against a quote from it.
How to install VoiceMode MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall VoiceMode MCP in Claude Code
$ claude mcp add --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' voicemode -- uvx voice-modeInstall VoiceMode MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"voicemode": {
"command": "uvx",
"args": [
"voice-mode"
],
"env": {
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install VoiceMode MCP in VS Code
.vscode/mcp.json
{
"servers": {
"voicemode": {
"type": "stdio",
"command": "uvx",
"args": [
"voice-mode"
],
"env": {
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install VoiceMode MCP in VS Code CLI
$ code --add-mcp '{"name":"voicemode","type":"stdio","command":"uvx","args":["voice-mode"],"env":{"OPENAI_API_KEY":"<YOUR_OPENAI_API_KEY>"}}'Install VoiceMode MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"voicemode": {
"command": "uvx",
"args": [
"voice-mode"
],
"env": {
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install VoiceMode MCP in Codex
$ codex mcp add voicemode --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' -- uvx voice-modeInstall VoiceMode MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.voicemode] command = "uvx" args = ["voice-mode"] [mcp_servers.voicemode.env] OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"
Install VoiceMode MCP in Gemini CLI
$ gemini mcp add -s user -e 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' voicemode uvx -- voice-modeInstall VoiceMode MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"voicemode": {
"command": "uvx",
"args": [
"voice-mode"
],
"env": {
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Configuration
OPENAI_API_KEYSecretOpenAI API key for cloud-based STT/TTS (optional - local services can be installed)
OPENAI_API_KEYVOICEMODE_AUDIO_FORMATAudio format: pcm, mp3, wav, flac, aac, opus (default: pcm)
VOICEMODE_DEBUGEnable debug mode with detailed logging (true/false)
VOICEMODE_DISABLE_SILENCE_DETECTIONDisable silence detection for continuous recording (true/false)
VOICEMODE_PREFER_LOCALPrefer local services over cloud when available (true/false, default: true)
VOICEMODE_SAVE_AUDIOVOICEMODE_SKIP_TTSSkip TTS and show text only for faster response (true/false)
VOICEMODE_WHISPER_MODELWhisper model: tiny, base, small, medium, large (default: base)
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubVoiceMode
Natural voice conversations with Claude Code (and other MCP capable agents)
New, 9 Nov 2026: Session Kit, from the people who brought you VoiceMode. A voice, a phone line and mail for your Claude Code sessions. Works on macOS; preliminary testing on Linux.
VoiceMode enables natural voice conversations with Claude Code. Voice isn't about replacing typing - it's about being available when typing isn't.
Perfect for:
- Walking to your next meeting
- Cooking while debugging
- Giving your eyes a break after hours of screen time
- Holding a coffee (or a dog)
- Any moment when your hands or eyes are busy
See It In Action
Quick Start
Requirements: Computer with microphone and speakers
Option 1: Claude Code Plugin (Recommended)
The fastest way for Claude Code users to get started:
# Add the VoiceMode marketplace
claude plugin marketplace add mbailey/voicemode
# Install VoiceMode plugin
claude plugin install voicemode@voicemode
## Install dependencies (CLI, Local Voice Services)
/voicemode:install
# Start talking!
/voicemode:converse
Option 2: Python installer package
Installs dependencies and the VoiceMode Python package.
# Install UV package manager (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Run the installer (sets up dependencies and local voice services)
uvx voice-mode-install
# Add to Claude Code
claude mcp add --scope user voicemode -- uvx --refresh --from voice-mode voicemode-mcp-launcher
# Optional: Add OpenAI API key as fallback for local services
export OPENAI_API_KEY=your-openai-key
# Start a conversation
claude converse
For manual setup, see the Getting Started Guide.
Features
- Natural conversations - speak naturally, hear responses immediately
- Works offline - optional local voice services (Whisper STT, Kokoro TTS)
- Low latency - fast enough to feel like a real conversation
- Smart silence detection - stops recording when you stop speaking
- Privacy options - run entirely locally or use cloud services
Compatibility
Platforms: Linux, macOS, Windows (native or WSL), NixOS Python: 3.10-3.14
Configuration
VoiceMode works out of the box. For customization:
# Set OpenAI API key (if using cloud services)
export OPENAI_API_KEY="your-key"
# Or configure via file
voicemode config edit
See the Configuration Guide for all options.
Permissions Setup (Optional)
To use VoiceMode without permission prompts, add to ~/.claude/settings.json:
{
"permissions": {
"allow": [
"mcp__voicemode__converse",
"mcp__voicemode__service"
]
}
}
See the Permissions Guide for more options.
Local Voice Services
For privacy or offline use, install local speech services:
- Whisper.cpp - Local speech-to-text
- Kokoro - Local text-to-speech with multiple voices
These provide the same API as OpenAI, so VoiceMode switches seamlessly between them.
Installation Details
Ubuntu/Debian
sudo apt update
sudo apt install -y ffmpeg gcc libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev
WSL2 users: The pulseaudio packages above are required for microphone access.
Fedora/RHEL
sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel
macOS
brew install ffmpeg node portaudio
NixOS
# Use development shell
nix develop github:mbailey/voicemode
# Or install system-wide
nix profile install github:mbailey/voicemode
From source
git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .
NixOS system-wide
# In /etc/nixos/configuration.nix
environment.systemPackages = [
(builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
Troubleshooting
| Problem | Solution |
|---|---|
| No microphone access | Check terminal/app permissions. WSL2 needs pulseaudio packages. |
| UV not found | Run curl -LsSf https://astral.sh/uv/install.sh | sh |
| OpenAI API error | Verify OPENAI_API_KEY is set correctly |
| No audio output | Check system audio settings and available devices |
Save Audio for Debugging
export VOICEMODE_SAVE_AUDIO=true
# Files saved to ~/.voicemode/audio/YYYY/MM/
Documentation
- Getting Started - Full setup guide
- Configuration - All environment variables
- Whisper Setup - Local speech-to-text
- Kokoro Setup - Local text-to-speech
- Development Setup - Contributing guide
Full documentation: voicemode.dev
Links
- Website: voicemode.dev
- GitHub: github.com/mbailey/voicemode
- PyPI: pypi.org/project/voice-mode
- YouTube: @getvoicemode
- Twitter/X: @getvoicemode
- Newsletter:
License
MIT - A Failmode Project
mcp-name: dev.voicemode/voicemode
VoiceMode MCP questions
How do I add VoiceMode MCP to Claude Code?
Run claude mcp add --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' voicemode -- uvx voice-mode in your terminal. Add --scope user to make it available in every project.
How do I add VoiceMode MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does VoiceMode work offline?
Yes, it can run entirely locally with optional local voice services for speech-to-text and text-to-speech.
Do I need an OpenAI API key to use VoiceMode?
It is optional; you can set it as a fallback for local services or when using cloud services.
Which platforms does VoiceMode support?
It runs on Linux, macOS, Windows (native or WSL), and NixOS, with Python 3.10-3.14.
How do I install VoiceMode for Claude Code?
The recommended way is to add the VoiceMode marketplace, install the plugin, then run the install command and converse command.
Can I avoid permission prompts when using VoiceMode?
Yes, you can allow the converse and service tools in your Claude settings to skip prompts.
