# voicemode

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 1417
- Author: mbailey
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/mbailey/voicemode
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/mcp/voicemode

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `OPENAI_API_KEY`, `VOICEMODE_DEBUG`, `VOICEMODE_SKIP_TTS`, `VOICEMODE_PREFER_LOCAL`, `VOICEMODE_AUDIO_FORMAT`, `VOICEMODE_WHISPER_MODEL`, `VOICEMODE_DISABLE_SILENCE_DETECTION` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-mode
```
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>

### Codex

**Platform CLI**
```bash
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-mode
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
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-mode
```
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>

## When to use it
- 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
- 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.

## Similar
- [voice-agents](https://affpapa.org/en/nevibecode/skills/voice-agents.md) — skill · 194 installs
- [speech-engine](https://affpapa.org/en/nevibecode/skills/speech-engine.md) — skill · 6500 installs
- [characteristic-voice](https://affpapa.org/en/nevibecode/skills/characteristic-voice.md) — skill · 2800 installs
- [speakturbo-tts](https://affpapa.org/en/nevibecode/skills/speakturbo-tts.md) — skill · 1000 installs
- [openai-whisper](https://affpapa.org/en/nevibecode/skills/openai-whisper.md) — skill · 7100 installs
- [faster-whisper](https://affpapa.org/en/nevibecode/skills/faster-whisper.md) — skill · 1800 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md