soliloquy-tts 0.7.3

A text-to-speech MCP server powered by Kokoro — gives Claude Code a voice

Soliloquy

A text-to-speech MCP server powered by Kokoro — gives Claude Code a voice.

One command to install. No config, no API keys, no cloud.

Why Soliloquy?

	Cloud TTS (ElevenLabs, OpenAI, etc.)	Soliloquy
Privacy	Text sent to third-party servers	Runs entirely on your machine
Cost	$0.18-15/1M chars	Free forever
Offline	No	Yes
Usage Limits	Quotas / rate limits	Unlimited
Latency	200-500ms (network)	~50-100ms (local)
AI Integration	Developer calls API from code	AI agent decides when to speak
Setup	API keys + billing	One command, no config

What You Can Do

Once installed, just talk to Claude naturally:

• "turn on auto speak" — automatically voice conversational responses
• "read this file aloud" — listen to docs, chapters, or articles
• "speak aloud" — voice a specific response
• "stop" — stop audio playback

Auto-Speak

The flagship feature. Auto-speak voices every Claude conversational response automatically using a background hook — no tool call needed, zero token overhead. It just works.

"Turn on auto speak"

From that point on, everything Claude says, you hear. Toggle it off just as easily:

"Turn off auto speak"

When you use read_aloud or speak explicitly, auto-speak steps aside and lets the explicit playback finish.

Speech Normalization

Soliloquy doesn't just read text literally — it understands what sounds natural:

• Code blocks become "See the code below" instead of reading syntax aloud
• Tables are summarized ("There's a table here with 5 rows")
• Symbols are spoken naturally (arrows become "to", URLs are simplified)
• Lists are enumerated ("First... Second... Third...")
• Paragraph breaks produce natural pauses between sections

Technical content and markdown-heavy responses sound like a person reading them to you, not a robot parsing characters.

Requirements

• macOS, Windows, or Linux
• Python 3.10+
• PortAudio (audio output library)

Platform	Install PortAudio
macOS	brew install portaudio
Windows	Bundled with sounddevice (no action needed)
Linux	sudo apt install libportaudio2

Note: First install downloads ~2GB of dependencies (PyTorch, model weights). First run also downloads the Kokoro-82M model from HuggingFace.

Optional: macOS Menu Bar Control

On macOS, you can install rumps for a menu bar icon that lets you stop playback instantly — no need to go through Claude Code:

pip install rumps

Without it, everything still works — you just use the stop command through Claude Code instead.

Quick Start

Make sure PortAudio is installed (see above), then:

uvx soliloquy-tts

That's it. This registers the MCP server, configures auto-speak, and sets everything up. Restart Claude Code afterward and you're good to go.

Requires uv. Install it with brew install uv (macOS), sudo apt install uv (Linux), or see the uv docs.

What happens when you run it

1. Registers Soliloquy as an MCP server with Claude Code
2. Writes a hook script for automatic voicing
3. Configures the Claude Code Stop hook

You only need to do this once. After that, Claude Code starts Soliloquy automatically in the background whenever you open a session.

With pip

pip install soliloquy-tts
soliloquy

Same setup flow. Run soliloquy from your terminal and it handles the rest.

How It Works

Soliloquy uses a hybrid architecture to share a single model across multiple Claude Code sessions:

• First session loads the Kokoro model and starts a local backend server
• Additional sessions detect the running backend and connect as lightweight proxies (near-instant startup, no extra memory)
• If the backend exits, the next session automatically takes over

This is completely transparent — no configuration needed.

Reference

Tools

speak — Synthesize and play text aloud.

Parameter	Default	Description
text	(required)	Text to speak
voice	af_heart	Voice ID
speed	1.0	Speed multiplier (0.5 - 2.0)
lang	en-us	Language code

read_aloud — Read a file aloud directly. Supports plain text and markdown.

Parameter	Default	Description
path	(required)	Path to the file to read
voice	af_heart	Voice ID
speed	1.0	Speed multiplier (0.5 - 2.0)
lang	en-us	Language code

stop — Stop audio playback immediately.

auto_speak — Toggle automatic voicing on or off.

list_voices — List all available voices.

Voices

28 voices across American and British English. Default is af_heart.

View all voices

Voice	Accent	Gender
af_heart	American	Female
af_alloy	American	Female
af_aoede	American	Female
af_bella	American	Female
af_jessica	American	Female
af_kore	American	Female
af_nicole	American	Female
af_nova	American	Female
af_river	American	Female
af_sarah	American	Female
af_sky	American	Female
am_adam	American	Male
am_echo	American	Male
am_eric	American	Male
am_fenrir	American	Male
am_liam	American	Male
am_michael	American	Male
am_onyx	American	Male
am_puck	American	Male
am_santa	American	Male
bf_alice	British	Female
bf_emma	British	Female
bf_isabella	British	Female
bf_lily	British	Female
bm_daniel	British	Male
bm_fable	British	Male
bm_george	British	Male
bm_lewis	British	Male

Languages

en-us (default), en-gb, ja, zh, es, fr, hi, it, pt-br

Uninstall

soliloquy --uninstall

This removes the MCP server registration, auto-speak hook, and all config files. Works with uvx soliloquy-tts --uninstall too.

Development

git clone https://gitlab.com/bw-stovall/soliloquy.git
cd soliloquy
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pytest tests/ -v

License

MIT