mcp-kokoro-tts

mcp-kokoro-tts

Local Kokoro-82M text-to-speech MCP server. When your agent calls speak, it synthesizes speech and plays it on your machine so you can hear the harness talk.

Works with any MCP client: Claude Desktop, Claude Code, Cursor, VS Code, opencode, Cline, and more. One short config block, no API keys — synthesis runs locally with Kokoro-82M.

On first start, the server provisions two things that are not on PyPI: the Kokoro-82M weights (~312 MB) into a local cache, and spaCy's English model (en_core_web_sm) into the same Python environment the server is running in. That second install is required because Kokoro's G2P pipeline loads spaCy, and a uvx / uv tool environment will not have the model unless this package puts it there.

Install

Add to your client's MCP config:

{
  "mcpServers": {
    "mcp-kokoro-tts": {
      "command": "uvx",
      "args": ["mcp-kokoro-tts"]
    }
  }
}

Requires Python 3.12 and uv. The first server start provisions Kokoro weights and the spaCy English model automatically.

To pre-download both without starting the MCP server:

uvx mcp-kokoro-tts-provision

Make the agent call it

Add one line to your AGENTS.md / CLAUDE.md / system prompt:

When the user wants to hear something spoken aloud, call the `speak` tool with clear, natural text.

Tools

speak

Synthesizes speech, writes a WAV file, and plays it locally.

Param	Required	Description
text	yes	Text to speak (max 500 chars)
voice	no	Voice id (e.g. af_heart) or absolute path to a .pt voice file
speed	no	Playback speed multiplier (default 1.0)

list_voices

Lists available Kokoro voices and the currently selected default.

Choosing your voice

Resolution order:

1. TTS_VOICE env var — voice id or absolute .pt path
2. A file in the package voices/ folder whose name starts with default
3. First .pt file in voices/ (alphabetical)
4. The model's bundled af_heart voice

{
  "mcpServers": {
    "mcp-kokoro-tts": {
      "command": "uvx",
      "args": ["mcp-kokoro-tts"],
      "env": {
        "TTS_VOICE": "af_heart"
      }
    }
  }
}

Environment variables

Variable	Description
TTS_VOICE	Default voice id or absolute .pt path
TTS_MODEL_DIR	Override model cache directory
TTS_HF_CACHE_DIR	Override Hugging Face hub cache directory
TTS_OUTPUT_DIR	Directory for generated WAV files
TTS_PLAY	Set to 0 to synthesize without local playback
HF_TOKEN	Optional Hugging Face token for faster downloads

Platforms

OS	Synthesis	Playback
macOS	yes	afplay
Linux	yes	ffplay, paplay, or aplay
Windows	yes	PowerShell MediaPlayer

espeak-ng is optional. English works without it; install it for better out-of-vocabulary coverage and some non-English languages.

Publishing

Tagging a version runs GitHub Actions publish.yml, which uploads to PyPI then the MCP Registry.

Publishing to PyPI uses the repo secret PYPI_TOKEN (a PyPI API token). GitHub trusted publishing can also be configured on the PyPI project; this workflow authenticates with the token so a first release does not depend on pending-publisher matching.

Release

1. Bump version in pyproject.toml (and server.json if you are not tagging yet)
2. Commit and tag: git tag v0.1.2 && git push origin v0.1.2
3. GitHub Actions runs publish.yml:
   • release — typecheck, test, build wheel/sdist
   • pypi-publish — upload to PyPI with PYPI_TOKEN
   • mcp-registry — OIDC → MCP Registry (after PyPI succeeds)

Development

cd mcps-tts
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pyright
pytest
python -m mcp_kokoro_tts

License

Apache-2.0. See LICENSE and NOTICE. Kokoro-82M model weights are downloaded separately under their Apache-2.0 license.