talk-to-claude 0.1.0
Voice MCP for natural conversations with Claude - simple, elegant, wake-word activated
Requires Python: >=3.10
Keywords: ai, claude, conversation, mcp, speech, voice

# 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
  ```bash
  # macOS
  brew install ffmpeg

  # Ubuntu/Debian
  sudo apt install ffmpeg

  # Windows
  winget install ffmpeg
  ```

## Installation

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

# Or via pip
pip install talk-to-claude
```

## Quick Start

1. **Set your OpenAI API key:**
```bash
export OPENAI_API_KEY=sk-...
```

2. **Add to Claude Code:**
```bash
claude mcp add talk-to-claude -- uvx talk-to-claude
```

3. **Start a voice conversation:**
```bash
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.

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

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

### `speak`
Text-to-speech only, no listening.

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

### `listen`
Listen only, no speaking. Great for continuing a conversation.

```json
{
  "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":

```bash
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

```bash
# 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