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! - 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 Playb
Add this skill
npx mdskills install ybouhjira/claude-code-ttsWell-architected TTS plugin with excellent docs, cross-platform support, and deterministic auto-speak.
1# Claude Code TTS Plugin23[](https://golang.org)4[](LICENSE)5[](https://github.com/ybouhjira/claude-code-tts/actions/workflows/ci.yml)6[](https://codecov.io/gh/ybouhjira/claude-code-tts)7[](https://modelcontextprotocol.io)89A 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!10111213## Features1415- **Deterministic Auto-Speak**: Every Claude response is automatically spoken (via Stop hook)16- **6 High-Quality Voices**: alloy, echo, fable, onyx, nova, shimmer17- **Worker Pool Architecture**: Non-blocking queue with concurrent processing18- **Mutex-Protected Playback**: One audio plays at a time, no overlapping19- **Cross-Platform**: macOS (afplay), Linux (mpv/ffplay/mpg123), Windows (PowerShell)20- **Standalone CLI**: `speak-text` binary for direct TTS without MCP2122## Quick Install2324```bash25# One-liner installation26curl -fsSL https://raw.githubusercontent.com/ybouhjira/claude-code-tts/main/install.sh | bash27```2829Or install manually:3031```bash32git clone https://github.com/ybouhjira/claude-code-tts.git ~/.claude/plugins/claude-code-tts33cd ~/.claude/plugins/claude-code-tts34make install35```3637## Requirements3839- **Go 1.21+** (for building from source)40- **OpenAI API Key** with TTS access41- **Audio Player**:42 - macOS: `afplay` (built-in)43 - Linux: `mpv`, `ffplay`, or `mpg123`44 - Windows: PowerShell (built-in)4546## Configuration4748Set your OpenAI API key:4950```bash51export OPENAI_API_KEY="sk-..."52```5354Or add to your shell profile (`~/.zshrc` or `~/.bashrc`).5556## Architecture5758```59┌─────────────────────────────────────────────────────────────┐60│ Claude Code │61│ │ │62│ MCP Protocol │63│ │ │64│ ┌──────────────────────▼──────────────────────────────┐ │65│ │ TTS MCP Server (Go) │ │66│ │ ┌─────────────────────────────────────────────┐ │ │67│ │ │ Tool Handlers │ │ │68│ │ │ speak(text, voice) │ tts_status() │ │ │69│ │ └─────────────┬─────────┴─────────────────────┘ │ │70│ │ │ │ │71│ │ ┌─────────────▼─────────────────────────────┐ │ │72│ │ │ Worker Pool (2 workers) │ │ │73│ │ │ ┌─────────┐ ┌─────────────────────┐ │ │ │74│ │ │ │ Job │───►│ Queue (50 slots) │ │ │ │75│ │ │ │ Submit │ └──────────┬──────────┘ │ │ │76│ │ │ └─────────┘ │ │ │ │77│ │ │ ┌────────▼────────┐ │ │ │78│ │ │ │ Worker 1 │ 2 │ │ │ │79│ │ │ └────────┬────────┘ │ │ │80│ │ └────────────────────────────│──────────────┘ │ │81│ │ │ │ │82│ │ ┌────────────────────────────▼──────────────────┐ │ │83│ │ │ OpenAI TTS API │ │ │84│ │ │ POST /v1/audio/speech │ │ │85│ │ │ Model: tts-1 │ │ │86│ │ └───────────────────┬────────────────────────────┘ │ │87│ │ │ │ │88│ │ ┌───────────────────▼────────────────────────────┐ │ │89│ │ │ Audio Player (Mutex Protected) │ │ │90│ │ │ macOS: afplay │ Linux: mpv │ Win: PowerShell │ │ │91│ │ └─────────────────────────────────────────────────┘ │ │92│ └──────────────────────────────────────────────────────┘ │93└─────────────────────────────────────────────────────────────┘94```9596## Usage9798### speak(text, voice)99100Convert text to speech and play it aloud.101102**Parameters:**103| Parameter | Type | Required | Description |104|-----------|------|----------|-------------|105| `text` | string | Yes | Text to speak (max 4096 chars) |106| `voice` | string | No | Voice to use (default: alloy) |107108**Available Voices:**109| Voice | Description |110|-------|-------------|111| `alloy` | Neutral, balanced |112| `echo` | Male, warm |113| `fable` | British accent |114| `onyx` | Deep male |115| `nova` | Female, friendly |116| `shimmer` | Soft female |117118**Example:**119```120Use the speak tool to say "Build completed successfully!" with the nova voice.121```122123### tts_status()124125Get the current status of the TTS system.126127**Returns:**128```json129{130 "worker_count": 2,131 "queue_size": 50,132 "queue_pending": 0,133 "total_processed": 15,134 "total_failed": 0,135 "is_playing": false,136 "recent_jobs": [...]137}138```139140## Automatic TTS (Deterministic)141142This plugin includes a **Stop hook** that automatically speaks the first sentence of every Claude response. No configuration needed - it just works.143144**How it works:**145```146Claude responds → Stop hook fires → First sentence extracted → Audio plays147```148149The hook runs in the background and won't block Claude's responses.150151### speak-text CLI152153A standalone binary for direct TTS without going through MCP:154155```bash156# Basic usage157speak-text "Hello world"158159# With voice selection160speak-text -voice onyx "Error occurred"161```162163Located at `~/.claude/plugins/claude-code-tts/bin/speak-text` after installation.164165## Project Structure166167```168claude-code-tts/169├── cmd/170│ ├── tts-server/171│ │ └── main.go # MCP server entry point172│ └── speak-text/173│ └── main.go # Standalone CLI binary174├── hooks/175│ └── auto-speak.sh # Stop hook for deterministic TTS176├── internal/177│ ├── audio/178│ │ └── player.go # Cross-platform audio playback179│ ├── server/180│ │ ├── server.go # MCP server & tool handlers181│ │ └── worker.go # Worker pool implementation182│ └── tts/183│ └── openai.go # OpenAI TTS client184├── plugin.json # Plugin metadata + hook config185├── Makefile # Build automation186└── install.sh # One-liner installer187```188189## Building from Source190191```bash192# Clone the repository193git clone https://github.com/ybouhjira/claude-code-tts.git194cd claude-code-tts195196# Build197make build198199# Install to Claude Code plugins200make install201202# Run tests203make test204```205206## Troubleshooting207208### "OPENAI_API_KEY environment variable is required"209Set your OpenAI API key:210```bash211export OPENAI_API_KEY="sk-..."212```213214### "No suitable audio player found on Linux"215Install one of: `mpv`, `ffplay`, or `mpg123`:216```bash217# Ubuntu/Debian218sudo apt install mpv219220# Fedora221sudo dnf install mpv222223# Arch224sudo pacman -S mpv225```226227### Audio not playing on macOS228Check that `afplay` works:229```bash230# Test with a sample audio file231afplay /System/Library/Sounds/Ping.aiff232```233234### Queue is full235The default queue size is 50. If you're hitting this limit:2361. Wait for current jobs to complete2372. Check `tts_status()` to see pending jobs2383. The queue will drain as jobs are processed239240### High latency241- OpenAI TTS API typically takes 1-3 seconds per request242- Audio files must download completely before playing243- Consider keeping messages short for faster feedback244245## API Costs246247This plugin uses OpenAI's `tts-1` model:248- **Cost**: ~$0.015 per 1,000 characters249- **Example**: "Hello, world!" (13 chars) = ~$0.0002250251## Contributing252253Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.254255## License256257MIT License - see [LICENSE](LICENSE) for details.258259## Credits260261- [OpenAI TTS API](https://platform.openai.com/docs/guides/text-to-speech)262- [mcp-go](https://github.com/mark3labs/mcp-go) - Go MCP implementation263- [Model Context Protocol](https://modelcontextprotocol.io)264
Full transparency — inspect the skill content before installing.