ybouhjira/claude-code-tts

A Text-to-Speech MCP server plugin for Claude Code that converts text to speech using OpenAI's TTS API. Get audio feedback from Claude as you work!
Features
- **Deterministic Auto-Speak**: Every Claude response is automatically spoken (via Stop hook)
- **6 High-Quality Voices**: alloy, echo, fable, onyx, nova, shimmer
- **Worker Pool Architecture**: Non-blocking queue with concurrent processing
- **Mutex-Protected Playback**: One audio plays at a time, no overlapping
- **Cross-Platform**: macOS (afplay), Linux (mpv/ffplay/mpg123), Windows (PowerShell)
- **Standalone CLI**: speak-text binary for direct TTS without MCP
Quick Install
Or install manually:
Requirements
- **Go 1.21+** (for building from source)
- **OpenAI API Key** with TTS access
- **Audio Player**:
- macOS: afplay (built-in)
- Linux: mpv, ffplay, or mpg123
- Windows: PowerShell (built-in)
Configuration
Set your OpenAI API key:
Or add to your shell profile (~/.zshrc or ~/.bashrc).
Architecture
Usage
speak(text, voice)
Convert text to speech and play it aloud.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| text | string | Yes | Text to speak (max 4096 chars) |
| voice | string | No | Voice to use (default: alloy) |
**Available Voices:**
| Voice | Description |
|-------|-------------|
| alloy | Neutral, balanced |
| echo | Male, warm |
| fable | British accent |
| onyx | Deep male |
| nova | Female, friendly |
| shimmer | Soft female |
**Example:**
tts_status()
Get the current status of the TTS system.
**Returns:**
Automatic TTS (Deterministic)
This plugin includes a **Stop hook** that automatically speaks the first sentence of every Claude response. No configuration needed - it just works.
**How it works:**
The hook runs in the background and won't block Claude's responses.
speak-text CLI
A standalone binary for direct TTS without going through MCP:
Located at ~/.claude/plugins/claude-code-tts/bin/speak-text after installation.
Project Structure
Building from Source
Troubleshooting
"OPENAI_API_KEY environment variable is required"
Set your OpenAI API key:
"No suitable audio player found on Linux"
Install one of: mpv, ffplay, or mpg123:
Audio not playing on macOS
Check that afplay works:
Queue is full
The default queue size is 50. If you're hitting this limit:
1. Wait for current jobs to complete
2. Check tts_status() to see pending jobs
3. The queue will drain as jobs are processed