Text-to-speech using the Kokoro-82M model, accelerated with MLX on Apple Silicon. Works three ways:
— gives local Claude and Codex clients (Claude Chat/Code/Cowork, Codex App, Codex CLI) the ability to speak text aloud and convert text to audio.
MCP server for Mac Kokoro-82M text-to-speech on Apple Silicon via MLX. Gives Claude Code, Chat, Cowork and Codex a voice. ChatGPT via a workaround. Speaks command line and clipboard. MCP Lazy-loads model (~600MB) for fast subsequent requests.
スター
4
ツール
—
稼働率
—
MCP server
ChatGPT Mac App — supported via kokoro-clipboard + Keyboard Maestro workaround (not MCP-native yet).
Command-line tools — kokoro and kokoro-clipboard commands for use in scripts, the terminal, or piped workflows
Both share the same generation engine and playback code, so pause/stop controls (via Stream Deck, hotkeys, etc.) work identically regardless of how audio was started.
The MCP server lazy-loads the model on first use and keeps it resident in memory (~600 MB), so subsequent requests start instantly. The CLI loads the model fresh each invocation (~3s startup), which is negligible for longer text.
Requirements
macOS on Apple Silicon (M1/M2/M3/M4)
Python 3.12 (not 3.13+ due to spacy/pydantic incompatibility)
espeak (brew install espeak)
ffmpeg (optional, only needed for MP3 export)
Setup
git clone https://github.com/scottschram/kokoro-tts-mcp.git
cd kokoro-tts-mcp
script/setup
script/setup builds the Python 3.12 venv and installs the pinned dependencies (raw equivalent: python3.12 -m venv .venv && .venv/bin/pip install -r requirements.txt). requirements.txt is pinned to the exact set known to work together — including the spaCy model en_core_web_sm — so this reproduces a known-good install with no separate python -m spacy download step. Requires Python 3.12 (not 3.13+). Confirm it works with script/speak-test.
Install the CLI commands
Symlink the kokoro* commands (kokoro, kokoro-clipboard, kokoro-pause, kokoro-stop) into ~/bin so they're on your PATH:
script/deploy
Idempotent and safe to re-run; run it once on each machine. ~/bin must be on your PATH. (It refuses to overwrite a real file that's in the way, so it won't clobber anything that isn't its own symlink.)
Usage
Command Line (kokoro)
kokoro "Hello, world." # play immediately
cat article.txt | kokoro # pipe input
kokoro -v bm_fable "Good morning, London." # British male voice
kokoro -f article.txt -o article.wav # save to WAV
kokoro -f article.txt --mp3 # save as MP3 to /tmp
kokoro -o talk.wav -p "Hello" # save AND play
kokoro -s 1.3 "A bit faster." # speed adjustment
kokoro -v list # show all voices
kokoro -h # full help
Playback via the MCP speak() tool: text ~2500 words or less starts within a few seconds; beyond that, first-audio latency grows roughly linearly with text size (~3 min at 3000 words, ~4 min at 5000). The delay sits in the MCP client's tool-call dispatch — not in the Kokoro pipeline, which streams audio within seconds at any size when driven via the CLI or a direct Python import. For long reads, use the CLI: kokoro -f file.txt -o file.wav (play with your preferred audio player) or cat file.txt | kokoro. Pause and stop work at any point during playback. See CLAUDE.md for the bisection.
kokoro is installed globally by script/deploy (see Setup), which symlinks all four kokoro* commands into ~/bin at once.
Command Line (kokoro-clipboard)
kokoro-clipboard # speak current clipboard
kokoro-clipboard --dry-run # preview cleaned speech text
kokoro-clipboard --silent-nontext # do not speak non-text clipboard
kokoro-clipboard --raw # skip markdown cleanup
kokoro-clipboard --max-chars 20000 # character cap before truncation
kokoro-clipboard --text "[kokoro]Hello[/kokoro]" --dry-run
kokoro-clipboard reads the current macOS clipboard and speaks it with markdown cleanup. If [kokoro]...[/kokoro] markers are present, only the text between markers is spoken. If markers are absent, the full clipboard text is spoken.
If clipboard content is non-text (image/PDF/file/URL), it speaks a short type message unless --silent-nontext is used.
Arguments:
Argument
Description
-v, --voice
Voice name (default: af_heart)
-s, --speed
Speed multiplier (default: 1.0)
--kokoro-cmd
Command/path used to invoke kokoro
--raw
Skip markdown cleanup
--silent-nontext
Exit without speaking when clipboard is non-text
--max-chars
Character cap before truncation (default: 20000)
--dry-run
Print final text instead of speaking
--text
Use provided text instead of reading clipboard
kokoro-clipboard is installed globally by script/deploy (see Setup), alongside the other kokoro* commands.
Keyboard Maestro (ChatGPT Mac workaround)
If ChatGPT Mac does not have MCP support for your account/workflow, you can still get spoken output by triggering kokoro-clipboard from Keyboard Maestro.
Create a new Keyboard Maestro macro group limited to ChatGPT (com.openai.chat).
Create a macro named Speak Clipboard.
Set trigger: The clipboard changes.
Add action: If Then Else with If All Conditions Met:
The clipboard contains [kokoro]
The clipboard contains [/kokoro]
In the Then branch, add action: Execute Shell Script.
"Say hello"
"Read that summary aloud using the British male voice bm_george"
"Save that explanation as an MP3"
MCP Server (Codex Mac App)
Codex Mac App and Codex CLI share the same global Codex config (~/.codex/config.toml).
After registering kokoro-tts with codex mcp add ... in a terminal, restart the Codex app.
Smoke Test
A quick script to verify the TTS pipeline without MCP or the full CLI — it speaks a phrase so you can hear that generation and playback work. Runs from any directory:
script/speak-test # default test phrase
script/speak-test "Custom text" # speak custom text
script/speak-test "Cheerio" bm_fable # specify voice
Tools
Tool
Description
speak(text, voice?, speed?)
Play text aloud (non-blocking, returns immediately)
pause()
Pause current playback
resume()
Resume paused playback
stop()
Stop playback immediately
status()
Return current state: idle, playing, or paused
user_stop_requested()
Check if the user stopped playback externally (returns True once, then clears)
28 English voices are available. The naming convention is: first letter = accent (a = American, b = British), second letter = gender (f = female, m = male).
British Female: bf_alice, bf_emma, bf_isabella, bf_lily
British Male: bm_daniel, bm_fable, bm_george, bm_lewis
Playback Control
Two shell scripts control playback from outside Claude (e.g., via Stream Deck, Keyboard Maestro, or a hotkey). They work with both the MCP server and the CLI — whichever is currently playing:
kokoro-pause — Toggle pause/resume. Also supports kokoro-pause pause, kokoro-pause resume, and kokoro-pause status.
kokoro-stop — Stop playback immediately and discard audio.
These work by creating/removing sentinel files (/tmp/kokoro-tts-pause, /tmp/kokoro-tts-stop) that the playback loop monitors.
Multi-Segment Playback
When Claude plays multiple segments sequentially (e.g., reading a list of items one by one), it polls status() until idle before starting the next segment. If the user stops playback externally (via kokoro-stop, Stream Deck, etc.), user_stop_requested() returns True once, signaling Claude to skip remaining segments instead of immediately starting the next one. The MCP stop() tool does not set this flag — it only applies to external stops, so Claude can distinguish "user wants silence" from "Claude decided to stop."
Text Preprocessing
MCP server and CLI — Negative numbers (e.g., -3) are expanded to words
(minus 3) before generation. The Kokoro phonemizer silently drops bare
negative-sign tokens, so without this preprocessing, -3 degrees would be
spoken as just degrees.
kokoro-clipboard — Clipboard text goes through additional preprocessing
to improve listening quality:
URLs expanded to speakable form (https://foo.com/path → https colon slash slash foo dot com slash path)
Negative numbers expanded (-3 → minus 3)
Punctuation between digits/words preserved (3.14, 10:30, $1,299.99 stay intact)
[kokoro]...[/kokoro] markers supported to limit what gets spoken
Use --dry-run to preview the cleaned text without audio
Known Issues
Python 3.13+ not supported — spacy and pydantic have incompatibilities on 3.13+. Use Python 3.12.
Short text workaround — Text under 25 characters is automatically padded to avoid an mlx-audio hang bug. This is handled transparently.
Do not install phonemizer — The phonemizer package conflicts with phonemizer-fork (pulled in by mlx-audio). Installing it causes out-of-dictionary words to be silently skipped. See requirements.txt for details.
misaki must be <0.9 — Version 0.9+ breaks EspeakWrapper.set_data_path. This is pinned in requirements.txt.
MCP server for Mac Kokoro-82M text-to-speech on Apple Silicon via MLX. Gives Claude Code, Chat, Cowork and Codex a voice. ChatGPT via a workaround. Speaks command line and clipboard. MCP Lazy-loads
MCP server for Mac Kokoro-82M text-to-speech on Apple Silicon via MLX. Gives Claude Code, Chat, Cowork and Codex a voice. ChatGPT via a workaround. Speaks command line and clipboard. MCP Lazy-loads model (~600MB) for fast subsequent requests.
最終チェックは 2026-10-27 です。 MCP server for Mac Kokoro-82M text-to-speech on Apple Silicon via MLX. Gives Claude Code, Chat, Cowork and Codex a voice. ChatGPT via a workaround. Speaks command line and clipboard. MCP Lazy-loads model (~600MB) for fast subsequent requests.