Mcp Kokoro Tts

io.github.mrfqcenticPublished by GitHub account mrfqcenticv0.1.4Updated Oct 24, 2026

Local Kokoro-82M TTS MCP server that synthesizes and plays speech on your machine

VerifiedSTDIODesktop onlyMedia & DesignAI & ML

Overview

AI-generated overview

A local text-to-speech MCP server that lets an assistant synthesize speech with the Kokoro-82M model and play it aloud on your machine.

What you can do
Synthesize speech from text (up to 500 characters) with an optional voice and speed, writing a WAV file and playing it locally through the speak tool. List the available Kokoro voices and the currently selected default voice. Choose a default voice via a voice id or a local voice file path, and optionally synthesize without playback.
When to use it
Useful when you want your assistant to read text aloud during a session, for example narrating results or confirming actions by voice, on a desktop machine with working audio playback.
Requirements
Runs locally via uvx and needs Python 3.12 and uv. The first start downloads the Kokoro-82M weights (about 312 MB) and the spaCy English model into the local environment. Playback uses afplay on macOS, ffplay, paplay or aplay on Linux, and PowerShell MediaPlayer on Windows; espeak-ng is optional. Optional environment variables include TTS_VOICE, TTS_MODEL_DIR, TTS_HF_CACHE_DIR, TTS_OUTPUT_DIR, TTS_PLAY and HF_TOKEN.
Before you install
The first run downloads several hundred megabytes of model files and installs the spaCy English model into the server's Python environment. Generated WAV files are written to a local output directory. HF_TOKEN is optional and only used for faster downloads. Desktop only; no audio playback on headless or web setups.

Installation

In SourceWeft

  1. Open Mcp Kokoro Tts in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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:

json
{  "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:

bash
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.

ParamRequiredDescription
textyesText to speak (max 500 chars)
voicenoVoice id (e.g. af_heart) or absolute path to a .pt voice file
speednoPlayback 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
json
{  "mcpServers": {    "mcp-kokoro-tts": {      "command": "uvx",      "args": ["mcp-kokoro-tts"],      "env": {        "TTS_VOICE": "af_heart"      }    }  }}

Environment variables

VariableDescription
TTS_VOICEDefault voice id or absolute .pt path
TTS_MODEL_DIROverride model cache directory
TTS_HF_CACHE_DIROverride Hugging Face hub cache directory
TTS_OUTPUT_DIRDirectory for generated WAV files
TTS_PLAYSet to 0 to synthesize without local playback
HF_TOKENOptional Hugging Face token for faster downloads

Platforms

OSSynthesisPlayback
macOSyesafplay
Linuxyesffplay, paplay, or aplay
WindowsyesPowerShell 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

bash
cd mcps-ttspython3.12 -m venv .venvsource .venv/bin/activatepip install -e ".[dev]"pyrightpytestpython -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.

Source: README.md at commit 17ca391

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.4LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.