voicemode — Claude Code MCP server: voice chat and setup
voicemode lets you speak to an AI agent and hear its replies. Use it when typing is awkward or you want a break from the screen.
claude mcp add --env OPENAI_API_KEY=<OPENAI_API_KEY> --env VOICEMODE_DEBUG=<VOICEMODE_DEBUG> --env VOICEMODE_SKIP_TTS=<VOICEMODE_SKIP_TTS> --env VOICEMODE_PREFER_LOCAL=<VOICEMODE_PREFER_LOCAL> --env VOICEMODE_AUDIO_FORMAT=<VOICEMODE_AUDIO_FORMAT> --transport stdio voicemode -- uvx voice-modeWhat voicemode does
The MCP server connects speech recognition with spoken agent responses. For local speech processing, you can install Whisper.cpp for transcription and Kokoro for text-to-speech. These local services use the same API as OpenAI.
You’ll need a computer with a microphone and speakers. Cloud services use the OPENAI_API_KEY environment variable; local services are available for offline use. The project lists Python 3.10–3.14 and support for Linux, macOS, Windows, WSL, and NixOS. On WSL2, microphone access requires PulseAudio packages.
What it helps with
- dictate a request when your hands are busy
- hear an agent’s reply instead of reading it
- transcribe speech locally with Whisper.cpp
- speak responses locally with Kokoro
Example prompts for the agent
- Talk me through a plan for changing this project.
- Listen to my description of the bug and suggest a fix.
- Use local speech services and reply aloud.
How to install voicemode
Platform CLI
claude mcp add --env OPENAI_API_KEY=<OPENAI_API_KEY> --env VOICEMODE_DEBUG=<VOICEMODE_DEBUG> --env VOICEMODE_SKIP_TTS=<VOICEMODE_SKIP_TTS> --env VOICEMODE_PREFER_LOCAL=<VOICEMODE_PREFER_LOCAL> --env VOICEMODE_AUDIO_FORMAT=<VOICEMODE_AUDIO_FORMAT> --transport stdio voicemode -- uvx voice-modeReplace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from voice-mode <command>
Platform CLI
codex mcp add voicemode --env OPENAI_API_KEY=<OPENAI_API_KEY> --env VOICEMODE_DEBUG=<VOICEMODE_DEBUG> --env VOICEMODE_SKIP_TTS=<VOICEMODE_SKIP_TTS> --env VOICEMODE_PREFER_LOCAL=<VOICEMODE_PREFER_LOCAL> --env VOICEMODE_AUDIO_FORMAT=<VOICEMODE_AUDIO_FORMAT> -- uvx voice-modeReplace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from voice-mode <command>
Config file
{
"mcpServers": {
"voicemode": {
"command": "uvx",
"args": [
"voice-mode"
],
"env": {
"OPENAI_API_KEY": "<OPENAI_API_KEY>",
"VOICEMODE_DEBUG": "<VOICEMODE_DEBUG>",
"VOICEMODE_SKIP_TTS": "<VOICEMODE_SKIP_TTS>",
"VOICEMODE_PREFER_LOCAL": "<VOICEMODE_PREFER_LOCAL>",
"VOICEMODE_AUDIO_FORMAT": "<VOICEMODE_AUDIO_FORMAT>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from voice-mode <command>
Config file
{
"servers": {
"voicemode": {
"type": "stdio",
"command": "uvx",
"args": [
"voice-mode"
],
"env": {
"OPENAI_API_KEY": "<OPENAI_API_KEY>",
"VOICEMODE_DEBUG": "<VOICEMODE_DEBUG>",
"VOICEMODE_SKIP_TTS": "<VOICEMODE_SKIP_TTS>",
"VOICEMODE_PREFER_LOCAL": "<VOICEMODE_PREFER_LOCAL>",
"VOICEMODE_AUDIO_FORMAT": "<VOICEMODE_AUDIO_FORMAT>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from voice-mode <command>
Platform CLI
gemini mcp add -e OPENAI_API_KEY=<OPENAI_API_KEY> -e VOICEMODE_DEBUG=<VOICEMODE_DEBUG> -e VOICEMODE_SKIP_TTS=<VOICEMODE_SKIP_TTS> -e VOICEMODE_PREFER_LOCAL=<VOICEMODE_PREFER_LOCAL> -e VOICEMODE_AUDIO_FORMAT=<VOICEMODE_AUDIO_FORMAT> voicemode uvx voice-modeReplace <…> with your own values. 2 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from voice-mode <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about voicemode
How do I install voicemode in Claude Code?
Run claude mcp add voicemode -e OPENAI_API_KEY=<OPENAI_API_KEY> -- uvx voice-mode. Replace <OPENAI_API_KEY> with your key if you use cloud services.
What does voicemode do?
It lets you talk to an AI agent and hear spoken replies. The server handles speech recognition and text-to-speech.
Can voicemode work offline?
Yes. Whisper.cpp provides local speech recognition, while Kokoro provides local text-to-speech. These services let you process speech locally.
