voice-mcp

A local MCP server that provides voice tools for Claude Code - speech-to-text using Whisper and text-to-speech using Supertonic.

Features

Speech-to-Text (Whisper)

• listen_and_confirm - Record speech, transcribe with Whisper, return transcript for confirmation
• listen_for_yes_no - Quick yes/no detection for binary decisions
• Local transcription using faster-whisper (no API calls)
• Automatic silence detection to stop recording
• Audio beeps to indicate recording start/end

Text-to-Speech (Supertonic)

• speak - Speak text aloud to the user
• Local synthesis using Supertonic (no API calls)
• Fast on-device generation (66M parameters)

Combined Tools

• speak_and_listen - Speak then listen for a full response (reduces round trips)
• speak_and_confirm - Speak then listen for yes/no (reduces round trips)

Requirements

• Python 3.10+
• uv package manager
• A microphone (for speech-to-text)
• Speakers/headphones (for text-to-speech)

Installation

1. Clone the repository:

   git clone https://github.com/jochiang/voice-mcp.git
   cd voice-mcp
   

2. Install dependencies:

   uv sync
   

3. Add to your Claude Code MCP settings (.mcp.json in your project or ~/.claude/settings.json):

   {
     "mcpServers": {
       "voice": {
         "command": "uv",
         "args": ["run", "--directory", "/path/to/voice-mcp", "voice-mcp"]
       }
     }
   }
   

4. Restart Claude Code to load the MCP server.

Usage

Voice Input

Trigger voice input by saying something like:

• "let me explain verbally"
• "I'll tell you verbally"

Claude will call listen_and_confirm, you'll hear a beep, speak your response, and hear another beep when recording stops. Claude will repeat the transcript back for confirmation.

For yes/no questions, Claude can use listen_for_yes_no which interprets your response as "yes", "no", or "unclear".

Voice Output

Ask Claude to speak responses:

• "say that out loud"
• "read that to me"

Claude will call speak to synthesize and play the audio through your speakers.

Voice Conversations

For back-and-forth voice conversations, Claude can use the combined tools:

• speak_and_listen - Ask a question and wait for a full answer
• speak_and_confirm - Ask a yes/no question and get confirmation

These reduce latency by combining speak + listen in a single tool call.

Dynamic Silence Detection

All listening tools accept a silence_seconds parameter (default: 2.5, minimum: 2.0). Claude can adjust this per-call based on context - for example, using a longer silence period if the user needs more time to think, or keeping it shorter for quick confirmations.

Customizing Speech Behavior

The tool descriptions include default guidance for how Claude speaks. To customize this behavior, add instructions to your CLAUDE.md file. Examples:

# Voice preferences
- When speaking, be brief and conversational
- Describe code changes at a high level, don't read syntax
- Summarize URLs instead of spelling them out

You can encourage different styles - more verbose explanations, different tone, etc.

Notes

• First-run downloads: Models download automatically on first use - Whisper small (~460MB) and Supertonic (~260MB)
• Silence detection: Recording stops after 2.5 seconds of silence (configurable per-call, min 2.0s)
• Platform: Developed on Windows, should work on macOS/Linux

Troubleshooting

No audio output from TTS:

• Some DACs require stereo output - the speak tool outputs stereo by default
• Check your default audio output device

Recording stops too quickly:

• The silence threshold may be too sensitive for your microphone
• Adjust SILENCE_THRESHOLD in src/voice_mcp/audio.py (default: 0.01)
• Claude can also pass a higher silence_seconds parameter per-call (default: 2.5, min: 2.0)

Recording doesn't stop fast enough:

• Claude can pass a lower silence_seconds parameter (minimum 2.0 seconds)

Configuration

Whisper (Speech-to-Text)

The Whisper model defaults to small running on CPU. To change this, edit src/voice_mcp/transcribe.py:

# Model options: tiny, base, small, medium, large-v3
_model = WhisperModel("small", device="cpu", compute_type="int8")

For GPU acceleration, change device="cpu" to device="cuda" (requires cuDNN).

Supertonic (Text-to-Speech)

The default voice is M1. Available voices can be found at the Supertonic voice gallery.

License

MIT