Claude Code Tts

What ybouhjira/claude-code-tts does

ybouhjira/claude-code-tts is a Go-based MCP server for the 🎧 Text-to-Speech category. It sends requested text to OpenAI's tts-1 model, downloads the resulting audio, and plays it through the host computer's audio system. The server is designed for Claude Code and also includes a standalone speak-text command for direct use outside MCP.

The main speak tool accepts text and an optional voice. Text is limited to 4096 characters, and the default voice is alloy. The available voices are alloy, echo, fable, onyx, nova, and shimmer. The tts_status tool reports worker count, queue capacity and pending work, processed and failed totals, current playback state, and recent jobs.

How it works

Claude Code communicates with the server over MCP. A speak request enters a queue handled by two workers. Audio playback is protected by a mutex, so only one generated audio file plays at a time even when multiple jobs are being processed.

The plugin also includes a Stop hook. When Claude finishes responding, the hook extracts the first sentence and sends it for background playback, allowing the response to return without waiting for audio. The queue has 50 slots. OpenAI TTS requests typically take one to three seconds, and audio must be downloaded before playback begins.

Supported playback commands are afplay on macOS, mpv, ffplay, or mpg123 on Linux, and PowerShell on Windows. The exact player available therefore depends on the operating system and local installation.

Setup and configuration

Install with the repository's shell installer, or clone the project into ~/.claude/plugins/claude-code-tts and run make install. Building from source requires Go 1.21 or newer according to the requirements section. Set OPENAI_API_KEY in the environment or shell profile before starting the server.

macOS includes the required afplay command. Linux users need one of the listed players installed. Windows playback uses the built-in PowerShell option. After installation, the standalone binary is available at ~/.claude/plugins/claude-code-tts/bin/speak-text.

Tools and capabilities

The ybouhjira/claude-code-tts MCP server includes:

• speak(text, voice): submits text to OpenAI TTS and plays the result.
• tts_status(): returns queue, worker, processing, failure, and playback information.
• Automatic first-sentence speech through the Claude Code Stop hook.
• The speak-text CLI for direct text-to-speech without an MCP request.
• Six selectable OpenAI voices and platform-specific audio playback.

Limitations and notes

An OpenAI API key with TTS access is required, and requests incur OpenAI usage costs. The queue holds 50 jobs by default; additional work may need to wait if it is full. Audio playback requires a compatible local player, especially on Linux.

The project is released under the MIT License.