使用说明

项目简介

Voicevox MCP 服务器是一个允许 LLM 客户端通过 Model Context Protocol (MCP) 调用 VOICEVOX 引擎进行语音合成的后端服务。它将 VOICEVOX 的语音合成能力封装成 MCP 工具，使得支持 MCP 协议的 LLM 应用，如 Cursor 等，能够方便地使用 VOICEVOX 进行文本到语音的转换。

主要功能点

语音合成即服务: 将 VOICEVOX 引擎的语音合成功能通过 MCP 协议对外提供。
工具集成: 以 MCP Tool 的形式集成 VOICEVOX，方便 LLM 客户端调用。
本地播放: 合成的语音可以在运行服务器的主机上直接播放。
跨平台支持: 支持 Windows 和 Docker (WSL2) 环境。

安装步骤

克隆仓库:

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

安装依赖:
```
npm install
```
配置环境变量:
- 复制 '.env_example' 文件并重命名为 '.env'。
- 根据你的 VOICEVOX ENGINE 设置修改 '.env' 文件中的 'VOICEVOX_API_URL' (VOICEVOX API 地址) 和 'VOICEVOX_SPEAKER_ID' (默认话者ID)。
- 确保 VOICEVOX ENGINE 正在运行，并且可以通过配置的 'VOICEVOX_API_URL' 访问。
- Windows 环境 还需要安装 VLC 媒体播放器并确保其路径已添加到系统环境变量中，以便播放合成的语音。
- Docker 环境 需要确保 WSL2 环境配置正确，并安装必要的 Linux 软件包 ('libsdl2-dev pulseaudio-utils pulseaudio')。

服务器配置

MCP 客户端需要配置连接到 Voicevox MCP 服务器的工具。以下是不同环境下的配置示例，请根据你的 MCP 客户端配置进行添加。

Windows 环境 (SSE 模式):

在 MCP 客户端的 'mcp.json' 配置文件中，添加如下 'tools' 配置：

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

'voicevox': 工具名称，用于在 MCP 客户端中标识和调用该工具。
'url': Voicevox MCP 服务器的 SSE 连接地址。默认配置下，Windows 环境使用 SSE 传输协议，端口为 '10100'，路径为 '/sse'。

Docker 环境 (Stdio 模式):

在 MCP 客户端的 'mcp.json' 配置文件中，添加如下 'tools' 配置：

{
  "tools": {
    "voicevox": {
      "command": "cmd",
      "args": [
        "/c",
        "docker",
        "run",
        "-i",
        "--rm",
        "-v",
        "/mnt/wslg:/mnt/wslg",
        "-e",
        "PULSE_SERVER",
        "-e",
        "SDL_AUDIODRIVER",
        "-e",
        "VOICEVOX_API_URL",
        "-e",
        "VOICEVOX_SPEAKER_ID",
        "your-local-docker-image-name"
      ],
      "env": {
        "PULSE_SERVER": "unix:/mnt/wslg/PulseServer",
        "SDL_AUDIODRIVER": "pulseaudio",
        "VOICEVOX_API_URL": "http://host.docker.internal:50031",
        "VOICEVOX_SPEAKER_ID": "919692871"
      }
    }
  }
}

'voicevox': 工具名称。
'command': 启动服务器的命令，这里使用 'cmd /c docker run -i --rm ...' 在 Docker 容器中运行服务器。
'args': 传递给 'docker run' 命令的参数，包括：
- '-i': 保持标准输入 (stdio) 打开，用于 MCP 通信。
- '--rm': 容器退出后自动删除。
- '-v /mnt/wslg:/mnt/wslg': 挂载 WSLg 目录，用于 Docker 容器访问宿主机的 PulseAudio 服务，实现音频输出。（仅 Docker 环境需要）
- '-e ...': 设置环境变量传递给 Docker 容器，包括 PulseAudio 配置、SDL 音频驱动、VOICEVOX API 地址和话者 ID。
- 'your-local-docker-image-name': 需要替换为你本地 Docker 镜像的名称，该镜像应该包含 Voicevox MCP 服务器的代码和运行环境。
'env': 设置运行环境的环境变量，用于 Docker 容器内部的服务器配置。
- 'PULSE_SERVER', 'SDL_AUDIODRIVER': 配置 Docker 容器内的音频输出，使其能够通过 PulseAudio 服务播放声音。（仅 Docker 环境需要）
- 'VOICEVOX_API_URL', 'VOICEVOX_SPEAKER_ID': 传递 VOICEVOX API 地址和话者 ID 到 Docker 容器内部。

注意: Docker 环境的配置较为复杂，需要确保 Docker 镜像已构建，并且 '/mnt/wslg' 目录挂载和 PulseAudio 配置正确。

基本使用方法

启动服务器:
- Windows 环境: 在项目根目录下，先执行 'npm run build' 构建项目，然后执行 'npm start' 启动服务器。
- Docker 环境: 服务器将在 MCP 客户端通过 'docker run' 命令启动，无需手动启动。
在 MCP 客户端中使用:
- 在支持 MCP 协议的客户端（例如 Cursor 等）中，配置好上述服务器连接信息后，即可调用 'voicevox' 工具。
- 调用 'voicevox' 工具时，需要提供 'text' 参数，即要合成语音的文本内容。
- 例如，在 Cursor 中，可以使用类似 '@voicevox text="你好"' 的指令来调用语音合成功能。
- 合成的语音将在运行 Voicevox MCP 服务器的主机上播放出来。

话者ID

可以通过 VOICEVOX ENGINE API 的 '/speakers' 接口查询可用的话者 ID 列表。默认使用的话者 ID 是 1 (四国めたん)。如果需要使用其他话者，请修改 '.env' 文件中的 'VOICEVOX_SPEAKER_ID' 环境变量。

关键词