使用说明

kokoro tts mcp

使用文本转语音科科罗-82M 模型，加速玻璃直线磨斜边机苹果硅公司。工作方式有三种：

MCP服务器 --使本地Claude和Codex客户端（Claude Chat/Code/Cowork、Codex App、Codex CLI）能够大声朗读文本并将文本转换为音频。
ChatGPT Mac应用程序 --支持通过 kokoro-clipboard +键盘大师解决方法（还不是MCP原生）。
命令行工具 — kokoro 和 kokoro-clipboard 用于脚本、终端或管道工作流的命令

两者共享相同的生成引擎和播放代码，因此无论音频是如何启动的，暂停/停止控件（通过流甲板、热键等）的工作方式都是相同的。

MCP服务器在首次使用时延迟加载模型，并将其保留在内存中（约600 MB），因此后续请求会立即启动。CLI在每次调用（~3s启动）时都会加载新的模型，对于较长的文本来说，这可以忽略不计。

需求

苹果硅上的macOS（M1/M2/M3/M4）
Python 3.12（由于spacy/pydanic不兼容，不是3.13+）
espeak(brew install espeak)
ffmpeg（可选，仅用于MP3导出）

设置

git clone https://github.com/scottschram/kokoro-tts-mcp.git
cd kokoro-tts-mcp

script/setup

script/setup 构建Python 3.12 venv并安装固定依赖项（原始等效项： python3.12 -m venv .venv && .venv/bin/pip install -r requirements.txt). requirements.txt 是钉住到已知可以协同工作的确切集合，包括spaCy模型 en_core_web_sm --因此，这再现了一个已知的良好安装，没有单独的 python -m spacy download 步骤。需要Python 3.12（不是3.13+）。确认它与 script/speak-test.

安装CLI命令

Symlink kokoro* 命令(kokoro, kokoro-clipboard, kokoro-pause, kokoro-stop)进入 ~/bin 所以它们在你的路径上：

script/deploy

可以安全地重新运行；在每台机器上运行一次。 ~/bin 必须在你的路径上。（它拒绝覆盖挡道的真实文件，所以它不会破坏任何不是它自己的符号链接的东西。）

用法

命令行(`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

通过MCP播放 speak() 工具：文本~2500字或更少，几秒钟内开始；除此之外，第一音频延迟与文本大小大致呈线性增长（3000个单词约3分钟，5000个单词约4分钟）。延迟位于MCP客户端的工具调用调度中，而不是位于Kokoro管道中，当通过CLI或直接Python导入驱动时，Kokoro管道会在几秒钟内以任何大小流式传输音频。对于长时间读取，请使用CLI： kokoro -f file.txt -o file.wav （使用您喜欢的音频播放器播放）或 cat file.txt | kokoro。播放过程中可随时暂停和停止工作。看 CLAUDE.md 对于二分法。

kokoro 由全球安装 script/deploy （参见设置)，它将所有四个符号链接起来 kokoro* 命令进入 ~/bin 马上。

命令行(`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 读取当前的macOS剪贴板，并通过markdown清理功能进行朗读。如果 [kokoro]...[/kokoro] 标记存在时，只说出标记之间的文本。如果没有标记，则朗读完整的剪贴板文本。

如果剪贴板内容是非文本（图像/PDF/文件/URL），则它会发出短消息，除非 --silent-nontext 使用。

论据：

参数	描述
`-v`, `--voice`	语音名称（默认值： `af_heart`)
`-s`, `--speed`	速度倍增器（默认值： `1.0`)
`--kokoro-cmd`	用于调用的命令/路径 `kokoro`
`--raw`	跳过标记清理
`--silent-nontext`	剪贴板为非文本时退出而不说话
`--max-chars`	截断前的字符上限（默认值： `20000`)
`--dry-run`	打印最终文本而不是讲话
`--text`	使用提供的文本而不是阅读剪贴板

kokoro-clipboard 由全球安装 script/deploy （参见设置)，与其他 kokoro* 命令。

键盘大师（ChatGPT Mac解决方法）

如果ChatGPT Mac不支持您的帐户/工作流的MCP，您仍然可以通过触发来获得语音输出 kokoro-clipboard 来自键盘大师。

创建一个新的键盘大师宏组，仅限于ChatGPT(com.openai.chat).
创建一个名为的宏 Speak Clipboard.
设置触发器： The clipboard changes.
添加操作： If Then Else 随着 If All Conditions Met:
- The clipboard contains [kokoro]
- The clipboard contains [/kokoro]
在 Then 分支，添加操作： Execute Shell Script.
配置shell脚本：
- 外壳： /bin/zsh
- 输入： None
- 脚本：

~/bin/kokoro-clipboard

可选变体：

~/bin/kokoro-clipboard --silent-nontext
~/bin/kokoro-clipboard -v bm_fable -s 1.1

使用说明：

这 If Then Else 设置仅标记：只有当两个标记都存在时，它才会说话。
在复制的文本内， kokoro-clipboard 只讲中间的文本 [kokoro]...[/kokoro].
如果您删除 If Then Else 门， kokoro-clipboard 将说出任何复制的ChatGPT文本。
非文本剪贴板项目（图像/文件/PDF）将被公布，除非 --silent-nontext 已设置。

MCP服务器（克劳德代码）

注册MCP服务器：

claude mcp add kokoro-tts -- \
    /path/to/kokoro-tts-mcp/.venv/bin/python3.12 \
    /path/to/kokoro-tts-mcp/mcp_server.py

然后在Claude Code中，你可以让Claude说话：

“打个招呼” “用英国男声bm_george大声朗读该摘要” “将该解释另存为MP3”

MCP服务器（克劳德桌面-聊天/协作）

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kokoro-tts": {
      "command": "/path/to/kokoro-tts-mcp/.venv/bin/python3.12",
      "args": ["/path/to/kokoro-tts-mcp/mcp_server.py"]
    }
  }
}

编辑后重新启动Claude应用程序。

MCP服务器（Codex CLI）

注册MCP服务器：

codex mcp add kokoro-tts -- \
    /path/to/kokoro-tts-mcp/.venv/bin/python3.12 \
    /path/to/kokoro-tts-mcp/mcp_server.py

然后在Codex CLI中，您可以要求Codex发言：

“打个招呼” “用英国男声bm_george大声朗读该摘要” “将该解释另存为MP3”

MCP服务器（Codex Mac应用程序）

Codex Mac应用程序和Codex CLI共享相同的全球Codex配置(~/.codex/config.toml). 注册后 kokoro-tts 随着 codex mcp add ... 在终端中，重新启动Codex应用程序。

冒烟测试

一个快速脚本，用于在没有MCP或完整CLI的情况下验证TTS管道——它会说出一个短语，这样你就可以听到生成和回放工作。从任何目录运行：

script/speak-test                          # default test phrase
script/speak-test "Custom text"            # speak custom text
script/speak-test "Cheerio" bm_fable       # specify voice

工具

工具	说明
`speak(text, voice?, speed?)`	大声播放文本（无阻塞，立即返回）
`pause()`	暂停当前播放
`resume()`	恢复暂停的播放
`stop()`	立即停止播放
`status()`	返回当前状态： `idle`, `playing`，或 `paused`
`user_stop_requested()`	检查用户是否从外部停止播放（返回 `True` 一次，然后清除）
`speak_and_save(text, output_path?, voice?, speed?, mp3?)`	生成音频并将其保存到文件
`list_voices()`	列出所有可用的声音

声音

有28种英语语音可供选择。命名约定是：第一个字母=重音(a =美国人， b =英国），第二个字母=性别(f =女性， m =男性）。

美国女性： af_heart（默认），af_alloy，af_aoede，af_bella，af_jessica，af_kore，af_nicole，af_nova，af_river，af_sarah，af_sky

美国男性： am_adam、am_echo、am_eric、am_fenrir、am_liam、am_michael、am_onyx、am_puck、am_santa

英国女性： bf_alice、bf_emma、bf_isabella、bf_lily

英国男性： bm_daniel、bm_fable、bm_george、bm_lewis

回放控制

两个shell脚本控制Claude外部的播放（例如，通过Stream Deck、Keyboard Maestro或热键）。它们可以与MCP服务器和CLI一起使用，以当前正在播放的为准：

kokoro-pause --切换暂停/恢复。还支持 kokoro-pause pause, kokoro-pause resume，以及 kokoro-pause status.
kokoro-stop --立即停止播放并丢弃音频。

这些通过创建/删除哨兵文件来工作(/tmp/kokoro-tts-pause, /tmp/kokoro-tts-stop)回放循环所监视的。

多段播放

当Claude按顺序播放多个片段时（例如，逐一读取项目列表），它会轮询 status() 直到空闲，然后再开始下一段。如果用户停止外部播放（通过 kokoro-stop、流甲板等）， user_stop_requested() 回报 True 一次，通知克劳德跳过剩余的片段，而不是立即开始下一个片段。MCP stop() 工具确实不设置此标志——它只适用于外部停止，这样克劳德就可以区分“用户想要沉默”和“克劳德决定停止”

文本预处理

MCP服务器和CLI --负数（例如。， -3)扩展为单词 (minus 3)在世代之前。Kokoro电话听筒默默地掉光了所以如果没有这种预处理， -3 degrees 将会是说话公正 degrees.

kokoro剪贴板 --剪贴板文本经过额外的预处理提高听力质量：

删除Markdown语法（标题、粗体、斜体、链接、围栏、表格等）
URL扩展为可说话的形式(https://foo.com/path → https colon slash slash foo dot com slash path)
负数扩大(-3 → minus 3)
保留数字/单词之间的标点符号(3.14, 10:30, $1,299.99 保持完整）
[kokoro]...[/kokoro] 支持标记以限制说话内容
使用 --dry-run 预览无音频的已清理文本

已知问题

不支持Python 3.13+ --spacy和pydantic在3.13+上不兼容。使用Python 3.12。
短文本解决方法 --25个字符以下的文本会自动填充，以避免mlx音频挂起错误。这是透明处理的。
不要安装 phonemizer --The phonemizer 包与冲突 phonemizer-fork （由mlx音频引入）。安装它会导致字典外的单词被自动跳过。看 requirements.txt 了解详情。
misaki 必须小于0.9 --版本0.9+中断 EspeakWrapper.set_data_path这是固定的 requirements.txt.

许可证

麻省理工学院

使用说明

kokoro tts mcp

需求

设置

安装CLI命令

用法

命令行(kokoro)

命令行(kokoro-clipboard)

键盘大师（ChatGPT Mac解决方法）

MCP服务器（克劳德代码）

MCP服务器（克劳德桌面-聊天/协作）

MCP服务器（Codex CLI）

MCP服务器（Codex Mac应用程序）

冒烟测试

工具

声音

回放控制

多段播放

文本预处理

已知问题

许可证

相关 MCP

多模态生成API服务

Hugging Face MCP服务器

语音处理服务

macOS通知服务

短视频生成工具

文本转语音服务

命令行(`kokoro`)

命令行(`kokoro-clipboard`)