RELATED 01
liter-llm
One MCP server for chat, embeddings, images, speech, OCR and batch jobs across many LLM providers
264GitHub stars
958/wknpm downloads
48popularity score
VoiceMode
Two-way spoken conversation with a coding agent through speech-to-text and text-to-speech
By Mike Bailey (individual) Python Local · stdio MediaAI and ML
72 popularity score ★ 1.4k ↓ 5.8k/mo
Connect your client
Local (PyPI)
Add in one click
Opens the app, which asks before it adds the server.
Or add it by command or config
FirstTerminal
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx voice-mode-installClaude CodeTerminal
claude mcp add voicemode -- uvx --refresh --from voice-mode voicemode-mcp-launcherClaude Desktopclaude_desktop_config.json
{
"mcpServers": {
"voicemode": {
"command": "uvx",
"args": [
"--refresh",
"--from",
"voice-mode",
"voicemode-mcp-launcher"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"voicemode": {
"command": "uvx",
"args": [
"--refresh",
"--from",
"voice-mode",
"voicemode-mcp-launcher"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"voicemode": {
"type": "stdio",
"command": "uvx",
"args": [
"--refresh",
"--from",
"voice-mode",
"voicemode-mcp-launcher"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.voicemode]
command = "uvx"
args = ["--refresh", "--from", "voice-mode", "voicemode-mcp-launcher"]Gemini CLITerminal
gemini mcp add --scope user voicemode uvx -- --refresh --from voice-mode voicemode-mcp-launcherSettings 8
OPENAI_API_KEY |
Optional: OpenAI key for cloud speech-to-text and text-to-speech; used as a fallback when local services are not running. |
|---|---|
VOICEMODE_TOOLS_ENABLED |
Optional: Comma-separated list of tool modules to load instead of the default converse and service. |
VOICEMODE_TOOLS_DISABLED |
Optional: Comma-separated list of tool modules to leave out; all others load. |
VOICEMODE_TTS_BASE_URLS |
Optional: Text-to-speech endpoints tried in order; default local Kokoro then OpenAI. |
VOICEMODE_STT_BASE_URLS |
Optional: Speech-to-text endpoints tried in order; default local Whisper then OpenAI. |
VOICEMODE_VOICES |
Optional: Preferred voices, comma-separated (e.g. af_sky,nova). |
VOICEMODE_SAVE_AUDIO |
Optional: Save recordings and speech under ~/.voicemode/audio for debugging. |
VOICEMODE_SERVE_TOKEN |
Optional: Bearer token required by the optional HTTP server mode. |
What it does
VoiceMode adds a voice channel to Claude Code and other MCP clients. The agent calls its converse tool to speak a message aloud through your speakers, and can then record your reply from the microphone, stop when you go quiet, and hand the transcript back as text. It is aimed at working with an agent while your hands or eyes are busy elsewhere.
Speech runs through OpenAI-compatible endpoints. By default it tries a local Whisper.cpp server for speech-to-text (127.0.0.1:2022) and a local Kokoro server for text-to-speech (127.0.0.1:8880) first, and falls back to the OpenAI API when an OPENAI_API_KEY is set. The service tool starts, stops, restarts and enables those local speech services, so the whole loop can stay on your own machine.
Out of the box version 8.12.0 registers only two tools, converse and service; the loader in voice_mode/tools/__init__.py loads every other tool module (conch, devices, diagnostics, statistics, providers and others) only when they are named in VOICEMODE_TOOLS_ENABLED, or when VOICEMODE_TOOLS_DISABLED is used to drop some instead. The conch tool coordinates speech when several agents share one voice so only one talks at a time. The package can also serve MCP over streamable HTTP or SSE for remote agents, binding to 127.0.0.1:8765 unless VOICEMODE_SERVE_HOST and VOICEMODE_SERVE_PORT say otherwise.
What it needs
| Runtime | Python 3.10+ |
|---|
A computer with a microphone and speakers; Linux, macOS, Windows (native or WSL) or NixOS; Python 3.10 to 3.14 and uv (the launch command uses uvx). System audio libraries: ffmpeg and PortAudio (plus ALSA/PulseAudio packages on Linux and WSL2). Either the local Whisper.cpp and Kokoro services, which the `uvx voice-mode-install` installer sets up, or an OpenAI API key for cloud speech (billed by OpenAI).
Limits
Only converse and service are loaded unless VOICEMODE_TOOLS_ENABLED or VOICEMODE_TOOLS_DISABLED is set. A recording stops after 3 seconds of silence by default (VOICEMODE_SILENCE_THRESHOLD) and is capped at 120 seconds (VOICEMODE_MAX_RECORDING_TIME). Without the local speech services running and without an OPENAI_API_KEY, it has nothing to speak or transcribe with. The configuration guide's MCP example uses `uvx --refresh voice-mode`, while the README and the plugin use the voicemode-mcp-launcher program; the page gives the launcher form. The legacy VOICEMODE_TOOLS setting is deprecated.
Who it suits
Suits a developer who wants to talk to Claude Code or another MCP agent hands-free on their own machine, and who can install audio libraries and either run local speech models or pay for OpenAI speech. Those who want no cloud audio can keep it fully local with Whisper.cpp and Kokoro. It is a poor fit for headless servers or containers without audio devices, and for anyone looking for a general audio-editing or music tool: it only speaks and listens for the agent.
Tools 2
converse- Speaks a message aloud and, optionally, records and transcribes the spoken reply
service- Checks, starts, stops, restarts, enables or disables the local Whisper, Kokoro and mlx-audio speech services