thai-tts-mcp
by Max2535
README.md
# thai-tts-mcp
Stdio MCP server with one tool, `speak_thai(text, out_path="", play=True)`, that speaks Thai text offline with [`pythainlp/MakHamTTS`](https://huggingface.co/pythainlp/MakHamTTS) (Kokoro-82M Thai, ONNX on CPU, 24 kHz, female voice). Handy for spoken notifications from Claude Code or any other MCP client.
## Register with Claude Code
Requires [uv](https://docs.astral.sh/uv/) and Python 3.12+.
```bash
claude mcp add -s user thai-tts -- uvx --from git+https://github.com/Max2535/thai-tts-mcp thai-tts-mcp
claude mcp list # thai-tts should show "Connected"
```
Drop `-s user` to register it for the current project only.
The first call downloads about 312 MB of model files from Hugging Face into the HF cache (`~/.cache/huggingface`), pinned to a fixed revision. After that the server loads them from the cache and makes no network calls.
## Tool
| Arg | Default | Meaning |
|---|---|---|
| `text` | required | Thai text, 1 to 5000 chars. Split on whitespace into chunks of at most 150 chars, synthesized and joined with a 0.15 s gap. |
| `out_path` | `""` | Save to this `.wav`. Empty means a temp file, deleted after playback. |
| `play` | `true` | Play through the default audio device. One playback at a time (process-wide lock). |
Playback uses `winsound` on Windows, `afplay` on macOS and `aplay` on Linux.
## Develop
```bash
uv sync
uv run pytest -q # the smoke tests download the model on first run
```
## Known limitations
- The model sometimes adds an "r" cluster to short syllables, for example กะ sounds like กระ and ตอน like ตรอน. Output varies on every call, so a retry often fixes it.
- English words and digits are read with Thai pronunciation ("deploy" becomes ดีพลอย, "150" becomes หนึ่งร้อยห้าสิบ). Acronyms read better spelled out in Thai.
- The first call takes a few seconds to load the model. Synthesis runs on CPU and is serialized by a lock.
- Built on `mcp` 2.x, where `FastMCP` is named `MCPServer`.
## License
- Code: Apache-2.0 (see `LICENSE`).
- Model [`pythainlp/MakHamTTS`](https://huggingface.co/pythainlp/MakHamTTS): Apache-2.0.
- Voice data [`pythainlp/MakHamTTS-dataset`](https://huggingface.co/datasets/pythainlp/MakHamTTS-dataset): CC-BY-4.0. Credit PyThaiNLP / MakHamTTS when you publish audio made with it. The dataset card does not say where the recordings came from, so check it yourself before commercial use.
- Dependencies: [PyThaiTTS](https://github.com/PyThaiNLP/pythaitts) (Apache-2.0), onnxruntime (MIT), mcp (MIT).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues