# voicemode [Health: Active]

**Category:** 🗣️ Conversational AI  
**Repository:** https://github.com/mbailey/voicemode  
**GitHub Stars:** 1443  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/voicemode

## Description
Natural voice conversations for AI assistants - STT/TTS via MCP

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "voicemode": {
    "command": "uvx",
    "args": ["voice-mode-install"]
  }
}
```

## Documentation

## What voicemode does

voicemode adds spoken interaction to AI assistants that support MCP. It captures speech through the computer microphone, sends it through a speech-to-text service, and produces spoken responses through text-to-speech. The main interaction is exposed through the `converse` MCP tool, while the `service` tool supports the voice-service workflow.

The package is intended for conversational use rather than replacing typed interaction. It can be useful while walking, cooking, or working away from the keyboard, and it includes silence detection to stop recording after speech ends.

Voice processing can use cloud services or local components. Whisper.cpp provides local speech recognition, while Kokoro provides local speech synthesis with multiple voices. These local services follow the same API shape as the OpenAI services, allowing VoiceMode to switch between them.

## How it works

A compatible assistant starts the VoiceMode MCP launcher over stdio. The assistant invokes the conversation capability, VoiceMode reads audio from the configured microphone, detects when speaking has stopped, and returns or plays the resulting interaction through the configured audio device.

The project supports Linux, macOS, Windows, Windows Subsystem for Linux, and NixOS. Python versions 3.10 through 3.14 are supported. A computer with a microphone and speakers is required.

Claude Code users can install the VoiceMode marketplace plugin and invoke `/voicemode:install` followed by `/voicemode:converse`. An alternative setup uses the Python installer package and registers `voicemode-mcp-launcher` with `claude mcp add`.

## Setup and configuration

The installer can set up the Python package, command-line tools, dependencies, and local voice services. The documented installation path uses `uv`; installing it first may be necessary. Manual source installation and NixOS development or system-wide installation are also available.

Cloud speech services use `OPENAI_API_KEY`. The key is optional when local voice services are configured. Configuration can also be edited with `voicemode config edit`.

Platform dependencies include audio and media packages. Ubuntu and Debian setups may need FFmpeg, PortAudio, ALSA, PulseAudio, and development packages; Fedora and RHEL use their corresponding ALSA and PortAudio packages. macOS setup uses Homebrew packages including FFmpeg and PortAudio. WSL2 users need PulseAudio packages for microphone access.

Claude Code permission rules can allow the `converse` and `service` MCP tools without repeated prompts. For debugging, setting `VOICEMODE_SAVE_AUDIO=true` saves recordings under `~/.voicemode/audio/YYYY/MM/`.

## Tools and capabilities

- `converse` for voice conversations between the user and the connected assistant.
- `service` for the VoiceMode service workflow.
- Speech-to-text through OpenAI-compatible services or local Whisper.cpp.
- Text-to-speech through OpenAI-compatible services or local Kokoro voices.
- Silence detection that ends recording after the user stops speaking.
- Local operation for offline use and privacy-sensitive deployments.
- Optional audio capture for troubleshooting.

## Limitations and notes

Audio access depends on operating-system permissions and an available microphone and output device. Cloud operation requires a correctly configured OpenAI API key. Local operation requires installing the relevant Whisper.cpp and Kokoro services. WSL2 needs additional PulseAudio support for microphone access.

The setup documentation focuses on Claude Code, although the server is designed for other MCP-capable agents as well. VoiceMode is released under the MIT license.

_Full upstream README: https://allmcps.com/mcp/voicemode/readme_