mcp-kokoro-tts

本地 Kokoro-82M 文本转语音 MCP 服务器。当你的智能体调用 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

Related MCP server: MCP TTS Server

让智能体调用它

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

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

工具

speak

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

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"
      }
    }
  }
}

环境变量

平台

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 许可证单独下载。