MCP TTS VOICEVOX

安装示例：

• Windows（任选其一）

  • Winget：winget install --id=Gyan.FFmpeg -e
  • Chocolatey：choco install ffmpeg
  • Scoop：scoop install ffmpeg
  • 官方构建版本：从 https://www.gyan.dev/ffmpeg/builds/ 或 https://github.com/BtbN/FFmpeg-Builds 下载，并将 bin 文件夹添加到 PATH

• macOS

  • Homebrew：brew install ffmpeg

• Linux

  • Debian/Ubuntu：sudo apt-get update && sudo apt-get install -y ffmpeg
  • Fedora：sudo dnf install -y ffmpeg
  • Arch：sudo pacman -S ffmpeg

PATH 设置：

• Windows：将 ...\ffmpeg\bin 添加到环境变量，然后重启 PowerShell/终端和编辑器（Claude/VS Code 等）
  • 验证：powershell -c "$env:Path" 输出中应包含 ffmpeg 路径
• macOS/Linux：通常会自动检测。必要时使用 echo $PATH 检查，并重启 shell。
• MCP 客户端（Claude Desktop/Code）：重启应用以重新加载 PATH。

验证：

ffplay -version

如果显示版本信息，则表示安装完成。CLI/MCP 将自动检测 ffplay 并使用 stdin 流式播放。

用户词典工具（dictionary 组）：

可以通过 --disable-tools / VOICEVOX_DISABLED_TOOLS 单独关闭任何工具，也可以通过 --disable-groups / VOICEVOX_DISABLED_GROUPS 按组关闭工具。

VOICEVOX 设置

播放选项

命令行参数的优先级高于环境变量。 完整且最新的选项列表始终可通过 npx @kajidog/mcp-tts-voicevox --help 查看。

# Basic settings
npx @kajidog/mcp-tts-voicevox --url http://192.168.1.100:50021 --speaker 3 --speed 1.2

# HTTP mode
npx @kajidog/mcp-tts-voicevox --http --port 8080

# With restrictions
npx @kajidog/mcp-tts-voicevox --restrict-immediate --restrict-wait-for-end

# Disable individual tools
npx @kajidog/mcp-tts-voicevox --disable-tools speak_player,synthesize_file

# Disable a tool group
npx @kajidog/mcp-tts-voicevox --disable-groups player

你可以使用 JSON 配置文件代替环境变量和 CLI 参数，也可以与它们一同使用。设置项较多时，这种方式会很有用。

优先级顺序： CLI 参数 > 环境变量 > 配置文件 > 默认值

生成配置文件

npx @kajidog/mcp-tts-voicevox --init

这会在当前目录中创建包含所有默认设置的 .voicevoxrc.json。可按需编辑。

使用自定义配置文件路径

npx @kajidog/mcp-tts-voicevox --config ./my-config.json

也可以通过环境变量设置：

VOICEVOX_CONFIG=./my-config.json npx @kajidog/mcp-tts-voicevox

.voicevoxrc.json 示例

{
  "url": "http://192.168.1.50:50021",
  "speaker": 3,
  "speed": 1.2,
  "http": true,
  "port": 8080,
  "disable-tools": ["synthesize_file"],
  "disable-groups": ["dictionary"]
}

键可以使用 kebab-case（use-streaming）、camelCase（useStreaming）或内部键名（defaultSpeaker）。如果当前目录中存在 .voicevoxrc.json，系统会自动加载。

用于远程连接：

启动服务端：

# Linux/macOS
MCP_HTTP_MODE=true MCP_HTTP_PORT=3000 npx @kajidog/mcp-tts-voicevox

# Windows PowerShell
$env:MCP_HTTP_MODE='true'; $env:MCP_HTTP_PORT='3000'; npx @kajidog/mcp-tts-voicevox

Claude Desktop 配置（使用 mcp-remote）：

{
  "mcpServers": {
    "tts-mcp-proxy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

从 WSL 连接到在 Windows 上运行的 MCP 服务：

1. 从 WSL 获取 Windows 主机 IP

# Method 1: From default gateway
ip route show | grep -oP 'default via \K[\d.]+'
# Usually in the format 172.x.x.1

# Method 2: From /etc/resolv.conf (WSL2)
cat /etc/resolv.conf | grep nameserver | awk '{print $2}'

2. 在 Windows 上启动服务

将 WSL 网关 IP 添加到 MCP_ALLOWED_HOSTS，以允许从 WSL 访问：

$env:MCP_HTTP_MODE='true'
$env:MCP_ALLOWED_HOSTS='localhost,127.0.0.1,172.29.176.1'
npx @kajidog/mcp-tts-voicevox

或使用 CLI 参数：

npx @kajidog/mcp-tts-voicevox --http --allowed-hosts "localhost,127.0.0.1,172.29.176.1"

3. WSL 配置（.mcp.json）

{
  "mcpServers": {
    "tts": {
      "type": "http",
      "url": "http://172.29.176.1:3000/mcp"
    }
  }
}

⚠️ 在 WSL 中，localhost 指的是 WSL 本身。请使用 WSL 网关 IP 访问 Windows 主机。

要与 ChatGPT 搭配使用，请将 MCP 服务以 HTTP 模式部署到云端，并确保其能够访问 VOICEVOX Engine。

1. 部署到云端

使用 Docker 部署到 Render、Railway 等平台（已包含 Dockerfile）。

2. 设置 VOICEVOX Engine

在本地运行 VOICEVOX Engine 并通过 ngrok 暴露，或将其与 MCP 服务一同部署。

3. 配置环境变量

4. 在 ChatGPT 中添加连接器

前往 ChatGPT 设置 → 连接器 → 添加 MCP 服务 URL（https://your-app.onrender.com/mcp）。

基本步骤与 ChatGPT 相同，但 VOICEVOX_PLAYER_DOMAIN 的值不同。

Claude Web 要求 ui.domain 使用基于哈希的专用域名。使用以下命令计算：

node -e "console.log(require('crypto').createHash('sha256').update('Your MCP server URL').digest('hex').slice(0,32)+'.claudemcpcontent.com')"

示例：如果 MCP 服务 URL 为 https://your-app.onrender.com/mcp：

node -e "console.log(require('crypto').createHash('sha256').update('https://your-app.onrender.com/mcp').digest('hex').slice(0,32)+'.claudemcpcontent.com')"
# Example output: 48fb73a6...claudemcpcontent.com

将此输出值设置为 VOICEVOX_PLAYER_DOMAIN。

注意：由于 ChatGPT 和 Claude Web 要求使用不同的 VOICEVOX_PLAYER_DOMAIN 值，单个实例无法同时为两个客户端提供服务。请分别部署独立实例，或根据目标客户端切换环境变量。

1. 检查 VOICEVOX Engine 是否正在运行

curl http://localhost:50021/speakers

2. 检查平台专用的播放工具

• 检查软件包是否已安装：npm list -g @kajidog/mcp-tts-voicevox
• 确认配置文件中的 JSON 语法正确
• 重启客户端

设置

git clone https://github.com/kajidog/mcp-tts-voicevox.git
cd mcp-tts-voicevox
pnpm install

命令

包管理器为 pnpm（不支持 npm / yarn）。

开发服务器位于 MCP 服务 Package 中，因此请使用筛选器运行：