Skip to main content
Glama
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).