mcp-kokoro-tts

mcp-kokoro-tts

本地 Kokoro-82M 文本转语音 MCP 服务。当你的 Agent 调用 speak 时，它会合成语音并在你的机器上播放，让你听见运行环境开口说话。

适用于任何 MCP 客户端：Claude Desktop、Claude Code、Cursor、VS Code、opencode、Cline 等。只需一段简短的配置，无需 API 密钥——语音合成由 Kokoro-82M 在本地运行。

首次启动时，服务会配置两项 PyPI 上没有的内容：将 Kokoro-82M 权重（约 312 MB）下载到本地缓存，并将 spaCy 的英语模型（en_core_web_sm）安装到服务运行所在的同一 Python 环境中。第二项安装是必需的，因为 Kokoro 的 G2P 流程会加载 spaCy，而 uvx / uv tool 环境中没有该模型，除非此软件包将其安装到环境中。

安装

添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "mcp-kokoro-tts": {
      "command": "uvx",
      "args": ["mcp-kokoro-tts"]
    }
  }
}

需要 Python 3.12 和 uv。首次启动服务时会自动配置 Kokoro 权重和 spaCy 英语模型。

如需在不启动 MCP 服务的情况下预先下载两者：

uvx mcp-kokoro-tts-provision

让 Agent 调用它

在 AGENTS.md / CLAUDE.md / 系统提示词中添加一行：

When the user wants to hear something spoken aloud, call the `speak` tool with clear, natural text.

工具

speak

合成语音、写入 WAV 文件，并在本地播放。

参数	必需	描述
text	是	要朗读的文本（最多 500 个字符）
voice	否	语音 ID（例如 af_heart）或 .pt 语音文件的绝对路径
speed	否	播放速度倍率（默认值为 1.0）

list_voices

列出可用的 Kokoro 语音和当前选定的默认语音。

选择语音

解析顺序：

1. TTS_VOICE 环境变量——语音 ID 或 .pt 文件的绝对路径
2. 软件包 voices/ 文件夹中名称以 default 开头的文件
3. voices/ 中按字母顺序排列的第一个 .pt 文件
4. 模型自带的 af_heart 语音

{
  "mcpServers": {
    "mcp-kokoro-tts": {
      "command": "uvx",
      "args": ["mcp-kokoro-tts"],
      "env": {
        "TTS_VOICE": "af_heart"
      }
    }
  }
}

环境变量

变量	描述
TTS_VOICE	默认语音 ID 或 .pt 文件的绝对路径
TTS_MODEL_DIR	覆盖模型缓存目录
TTS_HF_CACHE_DIR	覆盖 Hugging Face Hub 缓存目录
TTS_OUTPUT_DIR	生成的 WAV 文件目录
TTS_PLAY	设为 0 可在合成时不进行本地播放
HF_TOKEN	可选的 Hugging Face 令牌，用于加快下载

平台

操作系统	合成	播放
macOS	是	afplay
Linux	是	ffplay、paplay 或 aplay
Windows	是	PowerShell MediaPlayer

espeak-ng 是可选项。英语语音无需它即可使用；安装它可提升词汇表外词语的覆盖率，并支持部分非英语语言。

发布

为版本打标签会运行 GitHub Actions publish.yml，先上传到 PyPI，再上传到 MCP Registry。

向 PyPI 发布时会使用仓库密钥 PYPI_TOKEN（PyPI API 令牌）。也可以在 PyPI 项目中配置 GitHub 可信发布；此工作流使用令牌进行身份验证，因此首次发布无需依赖待处理发布者匹配。

发布版本

1. 在 pyproject.toml 中更新 version（如果尚未打标签，也要更新 server.json）
2. 提交并打标签：git tag v0.1.2 && git push origin v0.1.2
3. GitHub Actions 运行 publish.yml：
   • release — 类型检查、测试、构建 wheel/sdist
   • pypi-publish — 使用 PYPI_TOKEN 上传到 PyPI
   • mcp-registry — OIDC → MCP Registry（PyPI 发布成功后）

开发

cd mcps-tts
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pyright
pytest
python -m mcp_kokoro_tts

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。Kokoro-82M 模型权重会根据其 Apache-2.0 许可证单独下载。