talk-to-claude 0.1.0

Voice MCP for natural conversations with Claude - simple, elegant, wake-word activated

talk-to-claude 🎤

Voice MCP for natural conversations with Claude. Simple, elegant, wake-word activated.

Why?

Existing voice solutions loop endlessly, have too many features, and don't wait for you to actually speak. This MCP:

• Waits for speech - VAD-based detection, only activates when you talk
• Simple - ~400 lines of code, 10 config options
• Just works - Install, configure API key, talk

Prerequisites

• ffmpeg - Required for MP3 audio playback

  # macOS
  brew install ffmpeg
  
  # Ubuntu/Debian
  sudo apt install ffmpeg
  
  # Windows
  winget install ffmpeg
  

Installation

# Install via uvx (recommended)
uvx talk-to-claude

# Or via pip
pip install talk-to-claude

Quick Start

1. Set your OpenAI API key:

export OPENAI_API_KEY=sk-...

2. Add to Claude Code:

claude mcp add talk-to-claude -- uvx talk-to-claude

3. Start a voice conversation:

claude converse

Configuration

All configuration via environment variables (sensible defaults provided):

Variable	Default	Description
OPENAI_API_KEY	(required)	Your OpenAI API key
TTC_VOICE	nova	TTS voice: alloy, echo, fable, onyx, nova, shimmer
TTC_SPEED	1.0	Speech speed (0.25-4.0)
TTC_VAD_AGGRESSIVENESS	2	VAD sensitivity (0-3, higher = stricter)
TTC_SILENCE_MS	800	Silence before speech ends (ms)
TTC_MIN_SPEECH_MS	500	Minimum speech to process (ms)
TTC_WAKE_WORD	(none)	Optional wake word (e.g., "hey claude")
TTC_LISTEN_TIMEOUT	30	Max seconds to wait for speech
TTC_DEBUG	false	Enable debug logging

MCP Tools

converse

The main tool for voice conversations.

{
  "message": "Hello! How can I help you today?",
  "wait_for_response": true,
  "voice": "nova",
  "speed": 1.0
}

Returns:

{
  "status": "success",
  "message": "Hello! How can I help you today?",
  "transcription": "I need help with my code"
}

speak

Text-to-speech only, no listening.

{
  "message": "Got it, let me look into that."
}

listen

Listen only, no speaking. Great for continuing a conversation.

{
  "timeout": 30,
  "wake_word": "hey claude"
}

Wake Word Mode

Set TTC_WAKE_WORD=hey claude to enable passive listening that only activates when you say "Hey Claude":

export TTC_WAKE_WORD="hey claude"
claude converse

Now it will wait quietly until you say the wake word, then respond.

How It Works

1. VAD (Voice Activity Detection) using WebRTC VAD detects when you start speaking
2. Recording continues until silence is detected (configurable)
3. Whisper transcribes your speech to text
4. OpenAI TTS speaks Claude's response
5. Repeat!

Compared to VoiceMode

Feature	talk-to-claude	VoiceMode
Lines of code	~400	2000+
Config options	10	100+
Loops endlessly	No	Yes
Wake word	Yes	Yes
Multiple agents	No	Yes
DJ ducking	No	Yes

We focus on doing one thing well: natural voice conversations with Claude.

Development

# Clone
git clone https://github.com/bacharyehya/talk-to-claude
cd talk-to-claude

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run locally
python -m talk_to_claude.server

License

MIT