VoiceMode MCP — Use Cases, Install & Live Demo

Why use it

Key features

Local Whisper option — no cloud audio
Multiple TTS backends: OpenAI, ElevenLabs, local Coqui
Push-to-talk or voice-activated modes
Streams partial responses so you hear Claude thinking
Works in terminal alongside Claude Code CLI

Live Demo

What it looks like in practice

voicemode-mcp.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "voicemode-mcp": {
      "command": "uvx",
      "args": [
        "voice-mode"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "voicemode-mcp": {
      "command": "uvx",
      "args": [
        "voice-mode"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "voicemode-mcp": {
      "command": "uvx",
      "args": [
        "voice-mode"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "voicemode-mcp": {
      "command": "uvx",
      "args": [
        "voice-mode"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "voicemode-mcp",
      "command": "uvx",
      "args": [
        "voice-mode"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "voicemode-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "voice-mode"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add voicemode-mcp -- uvx voice-mode

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use VoiceMode

Drive a Claude Code session hands-free while reading on another screen

👤 Devs who read docs or designs on one monitor while coding ⏱ ~30 min intermediate

When to use: You're reading a design doc and want to dictate changes without alt-tabbing.

Prerequisites

Microphone + speakers — System audio configured — test with say "hello" or equivalent
Whisper model ready — voice-mode install-whisper downloads the local model

Flow

Start voice

Use voicemode. Listen for prompts and speak responses. Repeat after me: "ready"✓ Copied

→ TTS plays "ready"
Dictate a change

[spoken] Update src/auth.ts — use bcrypt instead of plain SHA256 for passwords.✓ Copied

→ Transcription correct; change applied; TTS confirms
Review

[spoken] Read me the diff.✓ Copied

→ TTS reads diff in chunks, pausable

Outcome: A working session where your hands never leave what they were doing.

Pitfalls

TTS talking over your prompts — Enable push-to-talk mode or a wake word

Combine with: filesystem

Code by voice for accessibility or RSI recovery

👤 Devs with RSI, low vision, or preferring speech input ⏱ ~60 min intermediate

When to use: You can't type for a while and need to keep shipping.

Prerequisites

Tolerable ambient noise — Quiet room; headset mic beats laptop mic

Flow

Baseline

[spoken] Use voicemode. Read the latest git diff out loud, pausing between files.✓ Copied

→ Clear TTS read
Workflow

[spoken] Refactor the user model in src/models/user.ts. Move password hashing into a method. Show me the plan first.✓ Copied

→ Plan spoken; confirmation required before changes

Outcome: A full coding session without keyboard input.

Pitfalls

Code symbols mispronounced by TTS — Configure the TTS phoneme dictionary for common programming terms

Combinations

Pair with other MCPs for X10 leverage

voicemode-mcp + filesystem

Voice-dictated code changes land in the repo

I'll dictate changes; apply them in files after reading each back.✓ Copied

voicemode-mcp + github

Dictate a PR description after voice-reviewing the diff

Read me the staged changes, then open a PR with a description I'll dictate.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
start_listening	mode: "ptt"\|"vad"	Begin a voice session	free or OpenAI Whisper API
speak	text: str, voice?: str	Any time Claude wants to surface something audibly	TTS provider-dependent
transcribe_last	none	Fetch what the user just said	Whisper call
stop_listening	none	End voice session	free

Cost & Limits

What this costs to run

API quota: Local: free. OpenAI Whisper: $0.006/min. ElevenLabs TTS: ~$0.30/1k chars.
Tokens per call: Audio pipelines are not token-costed directly
Monetary: Free with local stack; metered with cloud providers
Tip: Local Whisper + Coqui TTS is totally free but lower quality — start cloud, downgrade later

Security

Permissions, secrets, blast radius

Minimum scopes: microphone speakers

Credential storage: TTS/STT API keys in env

Data egress: Voice audio to TTS/STT provider if not local

Never use cloud STT in calls with confidential audio unless you trust the provider's retention policy

Troubleshooting

Common errors and fixes

Mic not detected

System audio permission — grant terminal/Claude Code mic access

Verify: `voice-mode test-mic` prints levels

TTS sounds robotic

Default is Coqui local — switch to OpenAI tts-1-hd via VOICE_MODE_TTS=openai

Lag between my speech and response

Use local Whisper-tiny for STT; cloud adds 500ms+

Alternatives

VoiceMode vs others

Alternative	When to use it instead	Tradeoff
macOS Dictation + say command	You just want basic OS-level voice	No integration with Claude's output — one-way only
Superwhisper / Wispr Flow	You want a polished native macOS dictation app	Not MCP-integrated; no agent-level workflows

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills