JinDaGe - voicevox-mcp-server MCP Details

article

README

🚀 语音合成服务器 Voicevox MCP

这是一个借助 Model Context Protocol (MCP)，能够使用 Voicevox、AivisSpeech 或 COEIROINK 的语音合成服务器。它适用于在 Cursor 等工具中，于 Claude 3.7 的代理模式下进行语音合成。

🚀 快速开始

必要条件

Windows 环境

Node.js 18 版本或更高
已安装并运行的 Voicevox ENGINE（可在本地通过 http://localhost:50000 访问）
VLC 媒体播放器（已添加到系统路径）

Docker 环境 (WSL2)

安装 Docker 和 Docker Compose
具备 WSL2 环境
已安装并运行的 Voicevox ENGINE（本地或 Docker 内部）
在 Linux 系统上已安装 sudo apt install libsdl2-dev pulseaudio-utils pulseaudio
对 /mnt/wslg 有访问权限

安装与配置

克隆代码库

git clone https://github.com/Dosugamea/voicevox-mcp-server.git
cd voicevox-mcp-server

安装依赖项

npm install

配置环境变量将 .env_example 复制为 .env 文件并按需修改：

VOICEVOX_API_URL=http://localhost:50021
VOICEVOX_SPEAKER_ID=1

运行方法

Windows 环境运行

在编辑器和其他窗口中分别执行以下命令启动服务器：

npm run build
npm start

Docker 环境运行

无需在编辑器中操作，直接运行即可。由于是 stdio 模式，无法直接启动。

配置方法

Windows 环境运行时

在 mcp.json 中添加以下内容：

        "voicevox": {
            "url": "http://localhost:10100/sse"
        }

若连接不稳定可考虑重新连接。

Docker 环境运行时

在 mcp.json 中添加以下内容（作者环境未验证）：

{
    "tools": {
        "voicevox": {
            "command": "cmd",
            "args": [
                "/c",
                "docker",
                "run",
                "-i",
                "--rm",
                "-v",
                "/mnt/wslg:/mnt/wslg",
                "-e",
                "PULSE_SERVER=unix:/tmp/pulseaudio.sock",
                "-e",
                "QT_QPA_PLATFORM=offscreen",
                "dosugamea/voicevox",
                "python3",
                "main.py"
            ],
            "env": {
                "LD_LIBRARY_PATH": "/usr/lib:/$LD_LIBRARY_PATH",
                "PULSE_SERVER": "unix:/tmp/pulseaudio.sock",
                "QT_QPA_PLATFORM": "offscreen"
            }
        }
    }
}

✨ 主要特性

关于说话人 ID

VOICEVOX_SPEAKER_ID=1 对应的是“Yuki”角色
其他 ID 对应的角色请参考 https://voicevox.ai/speaker/

🔧 技术细节

故障排除

与 Voicevox 的连接错误

确保 Voicevox 已正确安装并运行，特别是 Wails 应用版本需为 v3.0.0 或更高
检查是否有其他进程占用相关端口

打包失败

安装 .NET SDK：dotnet install sdk
确保 Node 版本正确：使用 nvm use 16

在 Docker 中无法启动 Voicevox

确保 Docker 正确安装且正在运行
检查是否有其他进程占用相关端口
确保 Wails 应用版本为 v3.0.0 或更高

配置错误

查看控制台输出以获取具体错误信息
可通过 npm run dev 以调试模式运行，便于发现和解决问题

voicevox-mcp-server