kokoro-tts-mcp

Cross-platform local text-to-speech MCP server. Give your AI assistant a voice — on Windows, macOS, and Linux.

Powered by Kokoro-82M. Free, fully offline, no API keys, no cloud calls.

What it does

Exposes two Model Context Protocol tools to any MCP-compatible AI client (Claude Code, ZCode, Cursor, Windsurf, Cline, ...):

With auto-speak enabled, your assistant speaks every response aloud — hands-free operation for accessibility, multitasking, or just vibe.

Related MCP server: ThotStream

Features

• 🖥️ Works everywhere — Windows, macOS, and Linux (this is the main reason this fork exists; the original is macOS-only)

• 🔒 100% local — synthesis and playback happen on your machine, nothing leaves it

• 🆓 Free — Apache 2.0 licensed, no API keys, no subscriptions

• 🌍 48 voices — American/British English, Spanish, French, Hindi, Italian, Japanese, Portuguese, Mandarin

• ⚡ Offline after setup — the model is downloaded once, then everything runs locally

• 🗣️ Auto-speak mode — the assistant narrates every response automatically

Requirements

Quick start

1. One-time initialization

Downloads model weights (~350 MB, one time) and sets up an isolated Python environment:

npx github:kalprajsolutions/kokoro-tts-mcp init

2. Add to your MCP client

Claude Code:

claude mcp add tts -- npx -y github:kalprajsolutions/kokoro-tts-mcp

Generic MCP config (ZCode, Cursor, Windsurf, Cline, Claude Desktop, ...):

{
  "mcpServers": {
    "tts": {
      "command": "npx",
      "args": ["-y", "github:kalprajsolutions/kokoro-tts-mcp"],
      "env": {
        "TTS_VOICE": "af_heart",
        "TTS_SPEED": "1.0"
      }
    }
  }
}

Windows note: if your client has trouble launching npx directly, use the cmd.exe wrapper that works everywhere:

{
  "mcpServers": {
    "tts": {
      "command": "cmd.exe",
      "args": ["/d", "/c", "npx", "-y", "github:kalprajsolutions/kokoro-tts-mcp"]
    }
  }
}

3. Talk to your assistant

Try: "Speak this: hello world", "Mute TTS", "Change voice to bf_emma", "Turn on auto-speak".

Voices

48 Kokoro voices. Prefix guide: af/am = American English, bf/bm = British English, ef/em = Spanish, ff = French, hf/hm = Hindi, if/im = Italian, jf/jm = Japanese, pf/pm = Portuguese, zf = Mandarin. f = female, m = male.

Full list: Kokoro-82M VOICES.md

Configuration

Environment variables (optional, shown above in the MCP config):

Runtime changes made through tts_config are persisted to ~/.kokoro-tts/state.json.

Platform support

Troubleshooting

"Python 3.10–3.12 is required but not found" — Install Python 3.10, 3.11, or 3.12 from python.org. On Windows, tick "Add python.exe to PATH" in the installer. Kokoro does not yet support Python 3.13+.

Linux: "No audio player found" — Install one of the supported players: sudo apt install pulseaudio-utils (paplay), sudo apt install alsa-utils (aplay), or sudo apt install ffmpeg (ffplay). On headless servers there may be no audio device; the generated WAV can still be inspected via the tool's error/duration output.

Windows: init fails on pip path — Use version ≥ 1.0.0 of this package (older versions of the original upstream had POSIX-only paths).

First speak call is slow — The Kokoro model weights are downloaded from Hugging Face on first use (~350 MB, cached in ~/.cache/huggingface). Later calls are fast and fully offline.

Model download fails / corporate proxy — Set the standard HTTPS_PROXY/HTTP_PROXY environment variables, or pre-download via huggingface-cli.

How it works

MCP client (Claude Code / ZCode / Cursor / ...)
        │  stdio (JSON-RPC)
        ▼
Node.js MCP server (this package)
        │  spawn                     │  platform dispatch
        ▼                            ▼
Python venv (Kokoro pipeline)     afplay / PowerShell /
  → generates 24 kHz WAV          SoundPlayer / paplay / aplay

Credits & attribution

This project is a cross-platform fork of claude-tts-mcp by Mitch Hazelhurst — thank you for the excellent original. Modified for Windows/macOS/Linux support by Kalpraj Solutions; see NOTICE for the full change list.

• TTS model: Kokoro-82M by hexgrad (Apache 2.0)

License

Apache License 2.0 — free for personal and commercial use.