cove-tts-mcp

把 GPT-SoVITS 语音合成包成一个远程 MCP 服务。AI 客户端调用 cove_tts 工具，传一段文字，拿回一个可以直接播放、下载的音频链接。

• 一个 Docker 镜像，容器里两个进程：api_v2.py（GPT-SoVITS 推理，9880，只在容器内）和 mcp_server.py（MCP 服务，9881，对外）

• MCP 走 streamable HTTP，端点是 /mcp/

• 默认模型是 HuggingFace 上公开的 OmniDimen/Gove（GPT-SoVITS v2ProPlus 微调），构建镜像时自动下载

• 仓库不带参考音频，部署时你自己提供一段（见下文）

• CPU 推理，不需要显卡

一、先准备参考音频

GPT-SoVITS 每次合成都要一段"参考音频"加上这段音频里说的话，用来定语气和音色。你需要准备：

• 一段 3 到 10 秒的音频，wav 最稳妥。单人、干净、没有背景音乐和杂音，一句完整的话。超出 3~10 秒会直接启动失败。

• 这段音频里说的那句话，一字不差，填进 REF_PROMPT_TEXT。

• 语言，zh 或 en，填进 REF_PROMPT_LANG。

声音主要由模型权重决定，参考音频影响语气、节奏和一部分音色。请只用你有权使用的声音。

参考音频放到容器里，三种方式任选一种：

REF_AUDIO_URL 必须是能直接下载到文件本身的地址（不是网盘的分享页面）。用了它以后每次容器重启都会重新下载一次。

Related MCP server: Bailian Voice Clone MCP

二、环境变量

启动时会先检查参考音频，任何一项不对容器直接退出，日志里 [prepare-ref] 开头的几行会写原因。

三、部署

任何能构建 Dockerfile、对外开放一个端口的地方都能跑：自己的服务器、云主机、各种容器平台。

需要知道的几件事

• 构建很慢：要下载约 1.8GB 模型、安装 CPU 版 torch，第一次构建通常 10~20 分钟。只改代码重新构建时，模型那一层有缓存的话会快很多（取决于平台是否保留构建缓存）。

• 启动也要等：容器起来后加载模型要 1~3 分钟，这段时间 /health 还连不上。

• 内存：模型常驻内存，内存太小会在加载时被系统杀掉。建议预留 4GB 以上，以你机器上实际观察为准。

• 端口：对外映射容器的 9881。

• 音频存在容器的 /tmp：容器重启就没了，链接也随之失效。

用 Docker 跑

docker build -t cove-tts-mcp .

# 方式 A：启动时下载参考音频
docker run -d --name cove-tts-mcp --restart unless-stopped -p 9881:9881 \
  -e MCP_API_KEY=换成你的密钥 \
  -e REF_AUDIO_URL=https://example.com/my-ref.wav \
  -e REF_PROMPT_TEXT="参考音频里说的那句话" \
  -e REF_PROMPT_LANG=zh \
  -e PUBLIC_BASE_URL=http://你的IP或域名:9881 \
  cove-tts-mcp

# 方式 B：挂载本地文件
docker run -d --name cove-tts-mcp --restart unless-stopped -p 9881:9881 \
  -v /path/to/my-ref.wav:/app/ref/ref.wav:ro \
  -e MCP_API_KEY=换成你的密钥 \
  -e REF_PROMPT_TEXT="参考音频里说的那句话" \
  cove-tts-mcp

docker logs -f cove-tts-mcp     # 看到 [start] mcp pid=... 就是起来了

公网使用请放在 HTTPS 反向代理后面（Caddy、Nginx 等），客户端连 https 地址。

在容器平台上

各家界面不同，要做的事是一样的：

1. 从 GitHub 导入这个仓库（或你的 fork），让平台用根目录的 Dockerfile 构建

2. 填好上面的环境变量

3. 把容器端口 9881 暴露出去，拿到一个 https 域名

4. 把这个域名填进 PUBLIC_BASE_URL，重启一次

我们自己是部署在 Zeabur 上的，供参考：用 Git 方式添加服务、选这个仓库，在 Networking 里把 9881 绑定域名。服务在 Zeabur 的 HTTPS 代理后面，代码里已经处理了代理转发的 https 信息，不需要额外设置。

验证

浏览器打开 https://你的域名/health：

• {"ok": true, "api_v2": "alive", "busy": false}：正常

• 返回 503：推理进程挂了，看日志里 [api_v2] 开头的行

• 打不开：还在加载模型，或者端口没映射对

四、接到 AI 客户端

地址写 https://你的域名/mcp/，结尾带斜杠。

密钥三种带法，服务端都认，按客户端支持的选：

能用请求头就用请求头。密钥放在地址里，会原样出现在服务器和平台的访问日志里。

支持 JSON 配置的客户端：

{
  "mcpServers": {
    "cove-tts": {
      "type": "http",
      "url": "https://你的域名/mcp/",
      "headers": { "X-API-Key": "你的密钥" }
    }
  }
}

claude.ai 的自定义连接器：URL 填上面的地址，认证选不需要登录，能填请求头就填 X-API-Key；不能填就用 ?key= 那种地址。

工具

cove_tts(text, text_lang="zh")

• text：要说的话，最多 500 字

• text_lang：zh 或 en

• 返回：合成时长、文件大小、一个签名链接 /audio/{id}?exp=…&sig=…

签名链接不含主密钥，只能访问这一个文件，AUDIO_TTL_SECONDS 之后失效，容器重启也会失效。链接可以放心发进聊天记录或群里。

五、常见问题

连不上，日志里 POST /mcp/ 是 401 密钥没带上或者不对。日志里会有一行 auth rejected ... has_x_api_key=... has_bearer=... has_query_key=...，看是哪种都没带。

客户端报 .well-known/oauth-... 相关错误 服务不用 OAuth，这些地址固定返回 404。客户端里认证方式选"不需要登录"，用请求头或 ?key= 带密钥。

Bad Request: No valid session ID provided 客户端手里的会话已经失效（最常见是服务重启过），服务端不认了。在客户端里把这个 MCP 断开重新连接即可。

容器一启动就退出 看 [prepare-ref] 开头的日志：没填 REF_PROMPT_TEXT、找不到参考音频、下载失败、时长不在 3~10 秒，都会写明。

合成返回"排队超过 600 秒" 同一时间只能合成一句，前面的任务太多或者太长。CPU 上一句话通常 10~30 秒。

读错字 叠字词和外文音译名是模型的弱项，换个说法。

六、已知限制

• 只支持中文和英文

• CPU 推理，一句话 10~30 秒，同一时间只合成一句，其余排队（最多等 600 秒）

• 音频存在容器 /tmp，重启即清空

• Gove 的 .pth 文件头是 06，这是 v2ProPlus 的版本标记，不是文件损坏

七、目录

├── Dockerfile            python:3.10-slim + CPU 版 torch
├── requirements.txt      推理需要的依赖（版本都锁了，改之前看注释）
├── download_models.sh    构建时下载模型并校验大小
├── prepare_ref.py        启动前下载、校验参考音频
├── start.sh              依次启动参考音频检查 → api_v2 → MCP，之后看守两个进程
├── mcp_server.py         MCP 服务：/mcp/、签名音频 /audio/{id}、/health、鉴权、排队、清理
└── app/
    ├── api_v2.py         GPT-SoVITS 原版推理接口
    ├── ref/              参考音频放这里（ref.wav），仓库里是空的
    ├── GPT_SoVITS/       GPT-SoVITS 源码（裁掉了训练相关）
    └── tools/            只保留推理用到的部分

许可与致谢

本仓库按 MIT 协议 发布。推理代码来自 GPT-SoVITS（MIT），模型在构建时从各发布方下载，各自遵循原许可，详见 THIRD_PARTY_NOTICES.md。