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
-
Clone the repository:
bash git clone https://github.com/jochiang/voice-mcp.git cd voice-mcp -
Install dependencies:
bash uv sync -
Add to your Claude Code MCP settings (
.mcp.jsonin your project or~/.claude/settings.json):json { "mcpServers": { "voice": { "command": "uv", "args": ["run", "--directory", "/path/to/voice-mcp", "voice-mcp"] } } } -
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:```markdown
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`:```python
# 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
