{
  "markdown": "# mcp-kokoro-tts\n\n<!-- mcp-name: io.github.mrfqcentic/mcp-kokoro-tts -->\n\nLocal 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.\n\nWorks 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](https://huggingface.co/hexgrad/Kokoro-82M).\n\nOn 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.\n\n## Install\n\nAdd to your client's MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-kokoro-tts\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-kokoro-tts\"]\n    }\n  }\n}\n```\n\nRequires Python 3.12 and [uv](https://docs.astral.sh/uv/). The first server start provisions Kokoro weights and the spaCy English model automatically.\n\nTo pre-download both without starting the MCP server:\n\n```bash\nuvx mcp-kokoro-tts-provision\n```\n\n## Make the agent call it\n\nAdd one line to your `AGENTS.md` / `CLAUDE.md` / system prompt:\n\n```\nWhen the user wants to hear something spoken aloud, call the `speak` tool with clear, natural text.\n```\n\n## Tools\n\n### `speak`\n\nSynthesizes speech, writes a WAV file, and plays it locally.\n\n| Param | Required | Description |\n|---|---|---|\n| `text` | yes | Text to speak (max 500 chars) |\n| `voice` | no | Voice id (e.g. `af_heart`) or absolute path to a `.pt` voice file |\n| `speed` | no | Playback speed multiplier (default `1.0`) |\n\n### `list_voices`\n\nLists available Kokoro voices and the currently selected default.\n\n## Choosing your voice\n\nResolution order:\n\n1. `TTS_VOICE` env var — voice id or absolute `.pt` path\n2. A file in the package `voices/` folder whose name starts with `default`\n3. First `.pt` file in `voices/` (alphabetical)\n4. The model's bundled `af_heart` voice\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-kokoro-tts\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-kokoro-tts\"],\n      \"env\": {\n        \"TTS_VOICE\": \"af_heart\"\n      }\n    }\n  }\n}\n```\n\n## Environment variables\n\n| Variable | Description |\n|---|---|\n| `TTS_VOICE` | Default voice id or absolute `.pt` path |\n| `TTS_MODEL_DIR` | Override model cache directory |\n| `TTS_HF_CACHE_DIR` | Override Hugging Face hub cache directory |\n| `TTS_OUTPUT_DIR` | Directory for generated WAV files |\n| `TTS_PLAY` | Set to `0` to synthesize without local playback |\n| `HF_TOKEN` | Optional Hugging Face token for faster downloads |\n\n## Platforms\n\n| OS | Synthesis | Playback |\n|---|---|---|\n| macOS | yes | `afplay` |\n| Linux | yes | `ffplay`, `paplay`, or `aplay` |\n| Windows | yes | PowerShell `MediaPlayer` |\n\n`espeak-ng` is optional. English works without it; install it for better out-of-vocabulary coverage and some non-English languages.\n\n## Publishing\n\nTagging a version runs GitHub Actions `publish.yml`, which uploads to **PyPI** then the **MCP Registry**.\n\nPublishing 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.\n\n### Release\n\n1. Bump `version` in `pyproject.toml` (and `server.json` if you are not tagging yet)\n2. Commit and tag: `git tag v0.1.2 && git push origin v0.1.2`\n3. GitHub Actions runs `publish.yml`:\n   - `release` — typecheck, test, build wheel/sdist\n   - `pypi-publish` — upload to PyPI with `PYPI_TOKEN`\n   - `mcp-registry` — OIDC → MCP Registry (after PyPI succeeds)\n\n## Development\n\n```bash\ncd mcps-tts\npython3.12 -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\npyright\npytest\npython -m mcp_kokoro_tts\n```\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE). Kokoro-82M model weights are downloaded separately under their Apache-2.0 license.\n",
  "bytes": 4138,
  "sha": "ec5d34f5b2667324862baa6a03c4c5a94d61e345534aac3ebf8f77f81af46434",
  "repo_slug": "mrfqcentic/mcp-kokoro-tts",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mrfqcentic_mcp_kokoro_tts_5ccac1db/readme"
}