mcp-kokoro-tts
Local text-to-speech server that synthesizes speech with Kokoro-82M and plays it audibly on your machine.
speak— convert text (up to 500 chars) into speech and play it locally; optionalvoiceandspeedparameters, with playback queued so utterances don't overlap.list_voices— list available Kokoro voices and show the currently selected default voice.stop— cut the utterance currently playing and discard anything queued behind it.settings— get the local settings page URL, the stop hotkey, and whether the keyboard listener is armed.Choose voices via
TTS_VOICEenv var or a.ptvoice file, with automatic fallback resolution.Run one shared server over streamable HTTP so multiple MCP clients share a single model and playback queue.
Hotkey barge-in (Ctrl+Shift) on macOS to interrupt playback; no API keys needed since synthesis is local.
Downloads and caches the Kokoro-82M model weights from Hugging Face, with optional HF_TOKEN support for faster downloads.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-kokoro-tts speak 'Hello, this is a test of the Kokoro text-to-speech server.'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-provisionRelated MCP server: mac-say-mcp
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. Playback goes through a single queue: the call returns as soon as its audio is queued, and utterances play back to back in call order instead of overlapping.
Param | Required | Description |
| yes | Text to speak (max 500 chars) |
| no | Voice id (e.g. |
| no | Playback speed multiplier (default |
list_voices
Lists available Kokoro voices and the currently selected default.
stop
Cuts the utterance playing right now and drops everything queued behind it. Same thing the hotkey below does, for clients that cannot press keys.
settings
Returns the local settings page URL, the current stop hotkey, and whether the keyboard listener is armed.
Stop hotkey (barge-in)
Hold Ctrl + Shift and playback stops immediately: the current sentence is cut and every queued utterance is discarded, so you can talk over the agent.
Change the chord on the local settings page the server prints at startup —
http://127.0.0.1:8765/ by default — where you press the new combination and
save. It is written to ~/.config/mcp-kokoro-tts/hotkey.json and picked up
without a restart.
A global keyboard listener needs Input Monitoring permission on macOS: the
server asks for it on startup, so the app running it shows up under System
Settings → Privacy & Security → Input Monitoring — switch it on and restart.
Without it the hotkey reports needs_input_monitoring; the stop tool and the
page's "Stop audio now" button keep working.
Choosing your voice
Resolution order:
TTS_VOICEenv var — voice id or absolute.ptpathA file in the package
voices/folder whose name starts withdefaultFirst
.ptfile invoices/(alphabetical)The model's bundled
af_heartvoice
{
"mcpServers": {
"mcp-kokoro-tts": {
"command": "uvx",
"args": ["mcp-kokoro-tts"],
"env": {
"TTS_VOICE": "af_heart"
}
}
}
}Shared server (one copy for many clients)
By default each MCP client starts its own server over stdio, so five open sessions load the model five times. Run one shared server over streamable HTTP instead:
TTS_TRANSPORT=http mcp-kokoro-tts # or: mcp-kokoro-tts --http --port 8766Then point clients at it:
{ "mcpServers": { "mcp-kokoro-tts": { "type": "http", "url": "http://127.0.0.1:8766/mcp" } } }Every client then shares one model and one playback queue. TTS_HTTP_HOST (default 127.0.0.1) and TTS_HTTP_PORT (default 8766) set the address.
Environment variables
Variable | Description |
| Default voice id or absolute |
| Override model cache directory |
| Override Hugging Face hub cache directory |
| Directory for generated WAV files |
| Set to |
| Directory holding |
| Port for the local settings page (default |
| Optional Hugging Face token for faster downloads |
Platforms
OS | Synthesis | Playback | Stop hotkey |
macOS | yes |
| yes (Quartz tap, needs Input Monitoring) |
Linux | yes |
| no |
Windows | yes | PowerShell | no |
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
Bump
versioninpyproject.toml(andserver.jsonif you are not tagging yet)Commit and tag:
git tag v0.1.2 && git push origin v0.1.2GitHub Actions runs
publish.yml:release— typecheck, test, build wheel/sdistpypi-publish— upload to PyPI withPYPI_TOKENmcp-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_ttsLicense
Apache-2.0. See LICENSE and NOTICE. Kokoro-82M model weights are downloaded separately under their Apache-2.0 license.
Available Tools
2 toolslist_voicesList voicesA
List Kokoro voices available to the speak tool and the currently selected default voice. Resolution order: TTS_VOICE env var, voices/default* file, first file in voices/, then the model's default af_heart voice.
Inputs: no named parameters. Returns: result
speakSpeakA
Synthesize speech with Kokoro-82M and play it on the user's machine. Call this when the user wants the harness to talk, read something aloud, or hear a spoken response. Always pass clear, natural text to speak. Default voice resolution: TTS_VOICE env var, voices/default* in the package, first file in voices/, then the bundled af_heart voice from the model.
Inputs: text (required), speed, voice. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one performs speech synthesis ('speak'), the other lists available voices ('list_voices'). No ambiguity between them, as they serve complementary roles in the TTS workflow.
Both tool names follow an imperative verb style ('speak', 'list_voices'), which is concise and predictable. 'list_voices' uses a verb_noun pattern, but the naming is consistent in tone and clarity for a small set.
With only 2 tools, the server is minimal yet well-scoped for its purpose: a text-to-speech harness. The count is appropriate; additional tools would likely be redundant.
The core operation (speak) is present, and the companion list_voices provides necessary context for voice selection. Minor gaps exist, such as no pause/stop or voice configuration tool, but these are not critical for basic TTS functionality.
Related MCP Connectors
MCP server for Text-to-Speech
Hosted text-to-speech MCP server: 66 voices in 9 languages, long-form narration, podcasts.
Remote text-to-speech MCP server with text_to_speech and list_voices tools. Free plan.
AI voice generation: text-to-speech and voice cloning from any MCP client.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables users to convert text into high-quality audio by accessing the OpenAI Text-to-Speech API. It supports customizable model selection and voice options for synthesized speech generation via the MCP protocol.1MIT
- AlicenseAqualityDmaintenanceMCP server for text-to-speech using macOS say command, enabling speech synthesis, audio file generation, and voice management.521 npm1MIT

leanvox-mcpofficial
AlicenseNot gradedqualityDmaintenanceEnables text-to-speech generation, voice cloning, dialogue creation, and other TTS operations through natural language in MCP-compatible AI assistants.20 npmMIT- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to speak by running local voice models using Chatterbox Turbo TTS or Kokoro TTS, with support for voice cloning, paralinguistic tags, and multiple voices.57 npm13MIT