SuperClonica text to speech

SuperClonica MCP 服务

为 Claude 和其他 MCP 客户端提供文本转语音功能，在你自己的计算机上运行：首次运行后即可离线使用，不限次数，支持 31 种语言。它是云端服务 https://superclonica.com/mcp 的本地版本，工具名称相同。语音来自 SuperClonica 目录。

支持 Windows、macOS 和 Linux，需使用 Python 3.10 或更高版本。不支持中文。

设置

你需要安装 uv，以使用 uvx 命令。首次启动时会安装引擎，需要一两分钟。首次调用 speak 时会下载语音模型（约 400 MB），仅需下载一次。

Claude Desktop。 将以下内容添加到 claude_desktop_config.json，然后重启应用：

{
  "mcpServers": {
    "superclonica": {
      "command": "uvx",
      "args": ["superclonica-mcp"],
      "env": { "SUPERCLONICA_API_KEY": "sc_..." }
    }
  }
}

如果应用找不到 uvx，请在 command 中填写它的完整路径。在 Windows 上，运行 where uvx 可查看路径；在 macOS 和 Linux 上，运行 which uvx。

Claude Code：

claude mcp add superclonica -e SUPERCLONICA_API_KEY=sc_... -- uvx superclonica-mcp

Cursor（~/.cursor/mcp.json）使用与 Claude Desktop 相同的 JSON。VS Code（.vscode/mcp.json）在 "servers" 下使用相同的条目，并添加 "type": "stdio"。

如果不使用 uvx，也可以通过以下方式启动相同的服务：pipx run superclonica-mcp，或先运行 pip install superclonica-mcp，再运行 python -m superclonica_mcp。

API 密钥是可选的。使用内置语音和目录中的免费语音无需密钥。安装已购买的语音或你自己的语音则需要密钥；创建密钥免费。

工具

工具	功能
list_voices(query?, limit?)	列出这台计算机上的语音；联网时还会列出目录中的语音。每个语音都会显示是否已安装、是否属于你、是否免费或需要购买，并附上对应页面。
speak(text, voice, language, format?, output_path?, include_audio?)	在这台计算机上将文本转换为语音，并保存为 mp3、wav 或 ogg。返回文件路径和时长；如果有请求，也会返回音频本身。每次调用最多处理 20000 个字符。不会覆盖现有文件。
install_voice(voice)	将你可以使用的语音下载到这台计算机。已有的版本不会重复下载。
buy_voice(voice)	返回该语音页面的链接。**此工具不会付款：**你需要在浏览器中购买，然后告知助手安装。
play(path)	使用系统播放器播放 mp3、wav 或 ogg 文件。
get_usage()	显示模型是否已加载、使用的设备以及所用文件夹。本地引擎没有使用限制。

voice 可以是 list_voices 返回的 ID、内置名称（F1–F5、M1–`M5）或精确名称。如果一个名称对应多个语音，你会看到候选项供你选择，不会进行猜测。

要使用自己的语音文件，请将其 JSON 放入 voices 文件夹。语音名称就是文件名。

购买语音

1. 提出语音需求，例如“找一位沉稳的旁白”。助手会调用 list_voices。
2. 如果语音需要购买，助手会调用 buy_voice，并提供打开购买窗口的链接。
3. 在浏览器中确认购买。只有你点击后才会购买。
4. 说“安装它”。之后即可离线使用该语音。

设置项

以下环境变量均为可选项。

变量	含义	默认值
SUPERCLONICA_API_KEY	用于安装已购买语音和你自己的语音的密钥	无
SUPERCLONICA_VOICES_DIR	语音文件夹	Windows %APPDATA%\SuperClonica\voices；macOS ~/Library/Application Support/SuperClonica/voices；Linux ~/.local/share/superclonica/voices
SUPERCLONICA_OUTPUT_DIR	音频文件夹	voices 文件夹旁的 audio
SUPERCLONICA_DEVICE	cpu 或 gpu	如果已安装 GPU 引擎，则使用 GPU；否则使用 CPU

在 NVIDIA GPU 上加速

uvx superclonica-mcp 会安装 CPU 引擎，而 CPU 和 GPU 引擎不能共用同一个环境。要使用 GPU 引擎（Windows 或 Linux x86-64，Python 3.11+），请单独创建一个环境：

uv venv superclonica-gpu --python 3.12
uv pip install --python superclonica-gpu superclonica-gpu-cuda
uv pip install --python superclonica-gpu --no-deps superclonica-mcp
uv pip install --python superclonica-gpu "mcp>=2.3,<3" "truststore>=0.10"

然后将该环境中的 Python 用作命令，参数设为 -m superclonica_mcp，并在 env 中设置 SUPERCLONICA_DEVICE=gpu。

出现问题时

• **“语音模型仍在加载”：**首次运行时会在后台下载模型。请一分钟后再试。
• **客户端未显示任何工具：**查看服务的日志（Claude Desktop：Settings → Developer）。服务只会将日志写入 stderr。
• **长文本超时：**使用 CPU 时，请分段朗读长文本。

许可证

Apache-2.0。语音模型为 Supertonic 3，采用其自有的 OpenRAIL-M 许可证，由引擎从原始来源下载。