ollama-tts-mcp
# ollama-tts-mcp
Offline text-to-speech for Claude Code: a local alternative to the ElevenLabs MCP.
Speech is generated on your Mac by an open-source Ollama speech model
([Phonon](https://ollama.com/library/phonon), Apache 2.0, 112 MB) through Ollama's
`/v1/audio/speech` endpoint. After the one-time model pull, nothing touches the network.
## Tools
| Tool | What it does |
|---|---|
| `speak` | Says text out loud. Runs in the background and queues behind earlier speech; `wait: true` blocks until done. |
| `text_to_speech` | Saves speech to a file: `wav` (default), `m4a` (AAC, ~10x smaller) or `aiff`. |
| `list_voices` | Lists the model's voices (Phonon has 38: Zoey, Hugh, Freya, Easton, Hadley, …). |
| `stop_speaking` | Stops playback and clears the queue. |
Markdown, code blocks and URLs are cleaned up before speaking, and long text is split
at sentence boundaries (the API takes at most 4,096 characters per request).
## Requirements
- Apple Silicon Mac, Ollama **0.40.11 or newer** (`brew upgrade ollama`)
- `ollama pull phonon` (once)
- Python 3.10+
If Ollama isn't running, the server starts `ollama serve` itself.
## Install
```bash
git clone https://github.com/HarsimarSingh23/ollama-tts-mcp.git
cd ollama-tts-mcp
ollama pull phonon
python3 -m venv .venv
.venv/bin/pip install "mcp>=1.9,<2"
claude mcp add --scope user ollama-tts -- "$PWD/.venv/bin/python" "$PWD/ollama_tts_mcp.py"
```
Start a new Claude Code session afterwards; MCP servers are loaded when a session starts.
## Configuration
Set these with `claude mcp add ... -e NAME=value`:
| Variable | Default | |
|---|---|---|
| `OLLAMA_TTS_VOICE` | `default` | Default voice |
| `OLLAMA_TTS_MODEL` | `phonon` | e.g. `phonon:multilingual` for French, German, Spanish, Portuguese (CC BY-NC 4.0) |
| `OLLAMA_TTS_OUTPUT_DIR` | `~/Desktop` | Where `text_to_speech` saves files |
| `OLLAMA_HOST` | `http://localhost:11434` | Ollama server |
| `OLLAMA_TTS_AUTOSTART` | `1` | Start `ollama serve` when it isn't running |
## Limits
- Phonon doesn't support speed or style instructions (Ollama returns an error for them).
- No MP3 output; use `m4a` for small files.
- Speech models currently run only on macOS in Ollama.
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: speak plays audio, text_to_speech saves to a file without playing, list_voices enumerates voices/models, and stop_speaking halts playback. The play-vs-save distinction between speak and text_to_speech is explicitly called out, leaving little room for misselection.
list_voices and stop_speaking follow a clean verb_noun pattern, and speak is a simple verb, but text_to_speech is a noun-phrase outlier rather than an action verb like convert_text_to_speech. The set remains highly readable and predictable overall, with only that minor deviation.
Four tools is a well-scoped surface for an offline TTS server: one playback tool, one file-export tool, one discovery tool, and one interruption tool. Each earns its place with no redundancy.
The core lifecycle is covered: discover voices/models, speak aloud, export audio, and stop playback. Minor gaps exist around playback control (e.g. pause/resume, volume/speed adjustment, or checking playback status), but agents can work around these.