VoiceMode: turning Claude Code into a voice-driven MCP agent
Natural voice conversations with Claude Code
At a glance
- What is it?
- VoiceMode is an MIT-licensed Python MCP server that adds speech input and spoken output to Claude Code and other MCP-capable agents. It is genuinely useful when your hands or eyes are occupied, but the local speech path and the cloud fallback are very different setups, and the documentation does not spell out the cost of mixing them.
- Who is it for?
- Adopt VoiceMode if you already run Claude Code as an MCP client and want a hands-free channel for situations where typing is impractical, and if you are willing to install local Whisper.cpp and Kokoro services or supply an OpenAI API key. Do not adopt it if you need a stable, documented latency budget, if you cannot grant microphone access to a terminal or WSL2 session, or if you expect a hosted service with an SLA.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem VoiceMode targets: input and output when your hands are busy
Claude Code is a terminal tool. It assumes a keyboard, a screen, and a user sitting in front of both. VoiceMode's README frames the gap directly: voice is not positioned as a replacement for typing but as an option for moments when typing is not possible. The examples it gives are concrete: walking to a meeting, cooking, resting your eyes, holding a coffee or a dog.
The audience is therefore narrower than "anyone who uses an AI coding agent". It is people who already have Claude Code installed and configured, who work in environments where a microphone and speakers are available, and who want a conversational channel rather than a batch one. Because VoiceMode implements the Model Context Protocol, the README notes it also works with other MCP-capable agents, but every installation path shown is Claude Code specific. If you are not an MCP client user, the material here gives you no worked example.
How the MCP server, speech services and Claude Code fit together
VoiceMode ships as a Python package (voice-mode on PyPI) plus an MCP launcher entry point. The README's manual registration command is:
claude mcp add --scope user voicemode -- uvx --refresh --from voice-mode voicemode-mcp-launcher
That tells Claude Code to spawn the MCP server through uvx. The server then exposes tools that the README names in its permissions example: mcp__voicemode__converse and mcp__voicemode__service. So the data flow is: your speech is captured, transcribed by a speech-to-text backend, passed into the agent as conversation content, and the agent's reply is synthesized back to audio by a text-to-speech backend.
The interesting architectural claim is that the local services present the same API as OpenAI. The README states that Whisper.cpp and Kokoro "provide the same API as OpenAI, so VoiceMode switches seamlessly between them". That is the design decision that makes the rest of the configuration coherent: there is one speech interface, and the backend behind it is a deployment choice rather than a code change. I cannot verify from the supplied material how much of the OpenAI surface is actually implemented, or whether every parameter maps cleanly. The README asserts parity; it does not enumerate it.
Two behaviours are documented rather than described in prose. Silence detection stops recording when you stop speaking, which matters because it removes the need for a push-to-talk key. And there is a debug switch, VOICEMODE_SAVE_AUDIO=true, which writes captured audio to ~/.voicemode/audio/YYYY/MM/. That path is the only place in the README where VoiceMode's on-disk footprint is stated.
Two installation routes, and why the plugin route is the shorter one
The README offers two paths. The plugin route is marked as recommended for Claude Code users and is four commands:
claude plugin marketplace add mbailey/voicemode claude plugin install voicemode@voicemode /voicemode:install /voicemode:converse
The second route installs the Python package and wires it up by hand. It requires uv first, then the installer, then the MCP registration, then an optional API key:
curl -LsSf https://astral.sh/uv/install.sh | sh uvx voice-mode-install claude mcp add --scope user voicemode -- uvx --refresh --from voice-mode voicemode-mcp-launcher export OPENAI_API_KEY=your-openai-key claude converse
Note what the two routes imply. The plugin route hides the dependency installation behind /voicemode:install; the Python route makes you run voice-mode-install yourself, which the README says "sets up dependencies and local voice services". Both routes end at the same place, but only the second one shows you the MCP registration line, which is the part you will need to debug if the server fails to start.
System dependencies are listed per platform and they are not trivial. On Ubuntu and Debian the README asks for ffmpeg, gcc, libasound2-dev, libasound2-plugins, libportaudio2, portaudio19-dev, pulseaudio, pulseaudio-utils and python3-dev. Fedora and RHEL get alsa-lib-devel, ffmpeg, gcc, portaudio, portaudio-devel and python3-devel. macOS gets ffmpeg, node and portaudio via Homebrew. NixOS users can run nix develop github:mbailey/voicemode or install the flake profile. This is a real audio stack, not a pure-Python dependency, and that is where most first-run failures will come from.
Configuration surface: environment variables, a config file, and permission prompts
VoiceMode claims to work out of the box, and the documented configuration is thin. There is the OPENAI_API_KEY environment variable for cloud speech, and there is a config file edited with:
voicemode config edit
The README points to a Configuration Guide for "all environment variables" but does not list them inline. The one variable it does show is VOICEMODE_SAVE_AUDIO, which is a debugging aid rather than a tuning knob. So the practical picture is: you get a working default, and the documented escape hatches are the API key, the config editor, and the audio dump. If you need to know which sample rate, which model, or which voice is in use, the README does not tell you here.
Permissions are a separate concern. By default, MCP tool calls in Claude Code can trigger confirmation prompts, which would defeat the purpose of a hands-free conversation. The README's fix is to add two entries to ~/.claude/settings.json under permissions.allow: mcp__voicemode__converse and mcp__voicemode__service. This is worth thinking about before you do it. You are pre-approving a tool that can capture microphone audio and send it to a speech backend. The README treats this as an optional convenience; it is also the moment where the trust boundary is set.
Where VoiceMode is the wrong tool
The README's troubleshooting table is short and it is honest about the failure modes it knows: no microphone access, uv not found, OpenAI API error, no audio output. The microphone row is the one to read carefully. It says to check terminal and application permissions, and that WSL2 needs the pulseaudio packages. That is a hint that audio capture under WSL2 is the fragile path, and the Ubuntu dependency list repeats the point by flagging the pulseaudio packages as required for WSL2 microphone access.
The larger limitation is that the README makes a latency claim without a number. It says conversations are "low latency" and "fast enough to feel like a real conversation". That is a subjective threshold, and it will differ sharply between the local path (Whisper.cpp plus Kokoro on your own hardware) and the cloud path (OpenAI over the network). Nothing in the supplied material quantifies either. If your use case depends on a response arriving within a specific window, you have no published figure to plan against, and you would have to measure it on your own machine.
There is also a scope limit. VoiceMode is a conversational channel, not a dictation tool for injecting text into an editor, and not a transcription service for recorded files. The README's own framing, that voice is for when typing is not possible, rules out the case where you are at a keyboard and want accuracy. Speech recognition on identifiers, file paths and code will not beat typing, and nothing here suggests VoiceMode tries to.
Alternatives and the difference in approach
The obvious comparison is with the agent's own text interface. Claude Code already gives you a REPL-style conversation; VoiceMode adds an audio transport on top of it through MCP. The difference is not capability but channel. If you are at a desk, the text interface is faster and more precise, and VoiceMode adds a microphone permission, an audio stack, and a speech backend to maintain. VoiceMode only wins when the desk is unavailable.
A second comparison is with running a general-purpose speech-to-text tool and pasting the result into the agent. That approach uses one program for transcription and leaves the agent unchanged. VoiceMode instead puts both directions inside the agent as MCP tools, so the reply is spoken back without you copying anything. The trade-off is coupling: your speech setup now depends on the MCP server starting correctly inside Claude Code, which is one more process to debug than a standalone transcriber. The README's own troubleshooting entries (uv not found, no audio output) are the failure points that a separate transcription tool would not introduce.
A third comparison is between VoiceMode's own two backends. Whisper.cpp and Kokoro run locally, which the README lists under privacy and offline use. OpenAI's speech services run remotely and need an API key. The README says the two are API-compatible, so the choice is about where audio is processed and what hardware you have, not about which features exist.
Maintenance, releases and what the MIT licence means here
VoiceMode is not archived, the default branch is master, and the last push recorded is 2026-09-09. The recent release list shows v8.12.0, v8.11.0 and v8.10.2 between late June and late July 2026, which suggests a regular cadence rather than a frozen project. The major version number is high for a tool at this stage, and the release naming gives no hint of breaking changes between them; the supplied material contains no changelog, so you cannot tell from here whether upgrading from v8.10.2 to v8.12.0 requires a config migration.
That matters because VoiceMode is installed in two places at once. There is the Python package, updated through uvx or uv tool install, and there is the Claude Code plugin, updated through the plugin marketplace. A version skew between the two is a plausible failure mode, and the README does not describe how the plugin and the package versions are kept in step. If you install via the plugin route, you should know which artefact /voicemode:install actually pulls.
The licence is MIT, which permits commercial and private use and modification, with the usual requirement to carry the copyright notice and permission notice. The README also describes VoiceMode as a Failmode project and gives an mcp-name of dev.voicemode/voicemode. MIT covers the VoiceMode code; it does not cover Whisper.cpp, Kokoro, or OpenAI's API terms, which are separate and which the README does not discuss. If you plan to process audio that you would not send to a third party, the local path is the one to configure, and you should confirm what each local service does with the audio before you rely on it.
Editorial conclusion
Adopt VoiceMode if you already run Claude Code as an MCP client and want a hands-free channel for situations where typing is impractical, and if you are willing to install local Whisper.cpp and Kokoro services or supply an OpenAI API key. Do not adopt it if you need a stable, documented latency budget, if you cannot grant microphone access to a terminal or WSL2 session, or if you expect a hosted service with an SLA. Before committing, verify three things yourself: that your platform's audio stack works (the README lists specific packages per distribution), that the MCP server registers correctly with claude mcp add, and which of the two speech paths you will actually run, because the local and cloud paths are configured differently.
Community notes