Skip to main content
Glama
VoxRelay MCP Server

VoxRelay MCP Server

by yyezii2

VoxRelay

本地语音服务。一个进程、一个端口、一个可选依赖,把 TTS 包成 OpenAI 兼容接口, 给任何支持 /v1/audio/speech 的客户端用。

POST http://127.0.0.1:8787/v1/audio/speech
{"input": "要念的话", "voice": "xiaoxiao", "speed": 1.0}
  • 五个 Python 文件,标准库实现,没有 Web 框架;MCP 和侧边栏面板都是可选的

  • 一个仓库就是一个包:package.json 管 DSH 插件,server.py 管服务,共用同一份 config.json

  • 引擎可叠:edge-tts(免费在线)→ Windows SAPI(离线兜底)→ 上游服务 → RVC 后处理

  • 任何一个引擎挂掉都会被降级绕过,保证一定有声音出来

  • 音色由你自己带,仓库不含任何模型(见 models/README.md)

快速开始

需要 Python 3.10+(Windows)。

git clone https://github.com/nico2905120737-lab/voxrelay.git VoxRelay
cd VoxRelay
powershell -ExecutionPolicy Bypass -File install.ps1
start.bat

浏览器打开服务窗口第一行打印的地址(默认 http://127.0.0.1:8787)就是试听页。 端口取自 config.json 的 port,改了要按新地址打开。

装完直接有 11 个音色(10 个微软在线音色 + 1 个系统 SAPI),够用再往下看。

面板不是必需的。想在 DSH 侧边栏里开关语音,安装时多带一个开关,然后重启 DSH:

powershell -ExecutionPolicy Bypass -File install.ps1 -RegisterDsh

出问题了先跑自检,它会逐项告诉你是哪一环坏了:

python smoke.py

详细的症状排查见 TROUBLESHOOT.md。

Related MCP server: ttsstt-mcp-server

接口

OpenAI 兼容 / 合成

方法

路径

说明

GET

/health

引擎状态、音色数、运行时长

GET

/v1/audio/voices

音色列表,含每个音色的 ready 状态

POST

/v1/audio/speech

OpenAI 兼容合成,返回音频流

GET

/say?text=..&voice=..

浏览器直接听

GET

/

试听页

状态与控制(面板用的就是这几个)

方法

路径

说明

GET

/v1/mode

开关、音色、引擎、音量、语速、三件套端口

POST

/v1/mode

改上面任意一项,字段按需给

GET

/v1/stack

组件安装位置 + 运行状态

POST

/v1/stack

{component:"gsv"|"rvc", path:"..."},path 留空恢复默认

GET

/v1/services

三个服务的 installed / running / port / reason

POST

/v1/service

{name, action:"start"|"stop"|"restart"}

POST

/v1/rescan

重扫 models/,并把新发现的音色并进来

POST

/v1/restart

重启本服务(保持原端口)

所有端口只在 config.json 定义一次,上面这些接口返回的也是同一份值。

curl -X POST http://127.0.0.1:8787/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input":"你好","voice":"xiaoxiao"}' -o out.mp3

请求体字段:input(或 text)、voice、speed、response_format、model。 超过 max_chars 会被拒绝,避免一次塞一本书进来。

自动朗读请带 X-VoiceHub-Auto: 1(等价于请求体 "auto": true):语音模式关闭时服务端 直接回 204,不合成、不出声。手动试听不要带,否则开关关着就听不到了。

带自己的音色

模型不进仓库。把目录丢进 models/ 就行,服务启动自动扫描:

models/gsv/myvoice/      ref.wav + prompt.txt        → 零样本克隆,不用训练
models/gsv/trained/      + *.ckpt + *.pth            → 微调权重
models/rvc/mymodel/      *.pth + *.index             → RVC 音色转换

想临时改音色显示名、语言、底嗓,在同目录放一个 voice.json。 完整约定见 models/README.md。

也可以用配置文件的老办法:在 config.json 的 voices 里手写一条,显式配置优先于扫描结果。

接 GPT-SoVITS / RVC

GPT-SoVITS:自己装一份(官方仓库,MIT), 用 api.py 起 HTTP 服务,然后把它填进 config.json:

"gsv": { "base_url": "http://127.0.0.1:9880" }

VoxRelay 不打包 GSV —— 它带 3G 底模和一套 CUDA 环境,捆进来只会让仓库变成 20G。

GSV 装在哪个盘都行,让 VoxRelay 知道路径即可:面板里点「设置安装位置」, 或者写 stack.json:{"gsv": "D:\\GPT-SoVITS"}。指向的目录里要有 run_api.py。

RVC:rvc.enabled = true,再起一个 worker 指向 rvc.worker。 worker 需要 torch,属于可选组件。

MCP 接入

mcp_server.py 把服务包成 MCP 工具(speak / set_voice_mode / list_voices), stdio 传输、零依赖,DSH 和 WorkBuddy 都能直接挂:

{ "command": "python", "args": ["mcp_server.py"] }

端口自动从 config.json 读,不用在 MCP 配置里写地址。 只有当服务不在本机、或者你想故意指到别处时,才需要设 VOICEHUB_BASE。

握手(initialize)时会按「朗读来源」(speech_mode)下发不同的 instructions:

  • panel(默认):面板在回合结束时自己念,不要主动调用 speak——模型再调一次就念两遍。

  • mcp:每轮回复后调用 speak 朗读要点,面板不自动念。

speech_mode 存在 voice_mode.json 里,可在面板「朗读来源」处随时切换,或用 set_speech_mode 工具切换(口令「让面板念 / 让 MCP 念」)。切完下一轮指令跟着变。

规则跟着服务走,不用在 DSH / WorkBuddy 各自的 agent 规则文件里再抄一遍。

DSH 侧边栏面板(可选)

面板和 MCP 改的是同一份 voice_mode.json:AI 说「打开语音」,面板 4 秒内自己刷成开启; 在面板上关掉,AI 也不再念。两边不会打架。

开关是服务端总闸,不是提示词约定。 enabled=false 时,所有带 X-VoiceHub-Auto: 1 (或 auto:true)的合成请求都会被直接回 204、不合成不出声——包括绕过 MCP 直连 HTTP 的 agent。手动试听和明确调用不带这个头,照常出声。

自动朗读由前端触发。 面板在 conversation.chat.turnTail(回合尾部)挂了一个朗读组件: 回复一结束,前端自己取正文、合成、播放,不再等模型记得调 speak。开关一动立刻生效; 打开历史会话不会重念旧消息;同一段文本在一个会话里只念一次。

朗读来源可在面板切换(panel 面板自动朗读 / mcp 由 AI 调 speak), 与 MCP 的 set_speech_mode 是同一份状态,谁先改都行、两边自动同步。

老版本 DSH 没有这个插槽时,注册失败会自动跳过,退化成「只靠 MCP 工具」——不会报错, 也不会让面板消失。

安装(只是把包登记进 DSH,不会重装服务):

powershell -ExecutionPolicy Bypass -File install.ps1 -RegisterDsh

它只动三样东西,改之前都会备份 profile 清单:

  1. 在 ~/.dsh/profiles/desktop/package.json 的 dependencies 里加一行 "voxrelay": "link:<本仓库绝对路径>",并在 dsh.profile.bundles 里加 voxrelay

  2. 把 node_modules/voxrelay 指向本仓库(软链,失败则退回目录联接)

  3. 清掉旧版 @local/voicehub-panel 的残留依赖和插入项

然后重启 DSH —— 宿主只在启动时读 profile。侧边栏出现面板就是成功。 撤掉用 install.ps1 -UnregisterDsh,服务本身不受影响。

不想用脚本就手动改:照上面三条来,bundles 里加一行 voxrelay 即可。 改完可以先用 python dsh_link.py status 看挂没挂对:

profile      C:\Users\你\.dsh\profiles\desktop
依赖         link:D:/你的路径/voxrelay
bundles      有
node_modules 链接 -> D:\你的路径\voxrelay
结论         已挂上

面板怎么找到服务:宿主半边(index.js)注册了同源接口 /voicehub/endpoint, 优先读服务启动时写的 endpoint.json(带 pid 校验,服务被强杀留下的死文件不会被采纳), 没有才退回 config.json 的 port。所以改端口只需重启服务,面板下次轮询自己跟上, 不用改面板配置、也不用重启 DSH。

服务没起时,面板能自己拉起来。除了 /voicehub/endpoint,宿主还挂了三条控制路由:

路由

作用

GET /voicehub/status

三件套状态 + 语音模式,不依赖 8787

POST /voicehub/service

{name:"GSV"|"VoiceHub"|"RVC", action:"start"|"stop"|"restart"}

POST /voicehub/mode

{enabled:true|false},总开关

连不上 8787 时面板不会只剩一个"填地址"的空壳,而是显示「服务未运行」:列出三件套状态, 给「启动语音(全套)」和每个组件的单独启动按钮。

这些路由不重写启停逻辑——start/stop 转手调 voice_services,总开关转手调 mcp_server.set_voice_mode,和「打开 mod1 / 关闭 mod1」、计划任务走的是同一套幂等逻辑、 同一份状态(services.json 意图 + 端口实际)。组件名和动作都有白名单,宿主不接受任意命令。

启停请求一律「立即返回、后台执行」:start 内部最长等 90 秒,同步等会把面板请求挂住, 所以前端靠原有的 4 秒轮询看服务自己起来。

「关闭全部服务」(面板底部「维护」区,要点两下确认)会停掉三个进程、关闭语音模式、释放显存。 服务是 DETACHED 起的,DSH 关掉之后它们仍在后台跑 —— 要清干净就用这个按钮,不用去命令行。 它走的是 /voicehub/mode {enabled:false} → mcp_server.set_voice_mode → stop_services, 不自己实现停进程的逻辑。「服务未运行」页里也有一个「全部停止」,用来清掉 VoiceHub 掉了、 但 GSV/RVC 还在吃显存的残局。

面板自己的自检(不需要启动 DSH):

node panel-selftest.mjs    # 宿主半边:路由、端口发现
node client-selftest.mjs   # 前端:三个插槽是否都注册上(含回合尾部朗读)

panel-selftest.mjs 检查包名和客户端 id 是否一致、apply() 能否注册路由、端点算出来的端口 是否与 config.json 对得上——这三条任一不满足,面板就会静默不出现。 client-selftest.mjs 用一个假 ctx 走一遍真实加载路径,确认 main、sidebar.panellist、 conversation.chat.turnTail 都注册成功;少一个,对应的功能就静默缺失。

目录

server.py            HTTP 服务 + 试听页
voice_engines.py     引擎层(edge / sapi / upstream / rvc)
voice_models.py      models/ 自动发现
voice_services.py    三个服务的启停、自愈、端口解析
mcp_server.py        MCP 封装
smoke.py             冒烟测试(另起临时实例自检)
index.js             面板宿主半边:/voicehub/endpoint,告诉前端服务在哪
client.js            面板前端 + 回合结束自动朗读(手写 React.createElement)
cordis.patch.yml     DSH 插入项:把面板挂进侧边栏
package.json         一个包两个身份:npm 包清单 + DSH 插件声明
dsh_link.py          把本包登记进 DSH profile / 撤销
panel-selftest.mjs   面板自检(假 ctx 走一遍真实加载路径)
client-selftest.mjs  前端自检(确认 main / 侧边栏 / 回合尾部三个插槽都注册上)
TROUBLESHOOT.md      按症状查的排查手册
config.example.json  默认配置(缺 config.json 时自动用它)
start.bat stop.bat   Windows 启停脚本
models/              你自己的音色模型放这里

已知限制

  • Windows 优先。SAPI 引擎和 start.bat 是 Windows 的,其他平台只剩 edge-tts 一档。

  • 缓存按 sha1(音色|语速|文本) 存 out/cache/:超过 cache.max_mb(默认 300MB)或 超过 cache.max_age_days(默认 7 天)自动清。启动时清一次,运行中每小时补一次, 不需要手动删。

  • edge-tts 是微软的在线服务,需要联网;断网时自动退到 SAPI。

  • 前端自动朗读依赖 DSH 的 conversation.chat.turnTail 插槽;没有这个插槽的客户端 只能靠模型主动调 speak。两种路径都受同一个开关管。

  • 自动朗读只念 assistant 正文:去掉代码块、表格、URL,超过 300 字按句截断; 同一段文本在一个会话里只念一次,打开历史会话不重念。

许可

代码 MIT。仓库不含音色模型和训练权重;GPT-SoVITS、RVC、edge-tts 各自遵循其原有许可证。 用谁的音色、发给谁,法律责任在你自己这边。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to speak aloud using text-to-speech functionality. Works with agents running inside devcontainers and provides configurable voice settings for creating chatty AI companions.
      6
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables speech-to-text and text-to-speech conversion using OpenAI-compatible APIs. Supports customizable models, voices, and output directories.
      GPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to narrate internal thoughts, announce tool actions, and speak final responses aloud through local cross-platform text-to-speech. It exposes dedicated audio tools over stdio JSON-RPC for MCP-compatible clients.
      MIT