VOICEVOX TTS MCP

VOICEVOX TTS MCP

英语 | 日本语

使用VOICEVOX的文本转语音MCP服务器

🎮 尝试浏览器演示 --直接在浏览器中测试VoicevoxClient

你能做什么

• 让你的AI助手说话 --来自Claude Desktop等MCP客户端的文本转语音
• UI音频播放器（MCP应用程序） --使用交互式播放器（ChatGPT/Claude Desktop/Claude Web等）在聊天中直接播放音频
• 多角色对话 --在一次通话中按段切换扬声器
• 流畅播放 --队列管理、即时播放、预取、流式传输
• 跨平台 --适用于Windows、macOS、Linux（包括WSL）

UI音频播放器（MCP应用程序）

UI Audio Player

这 voicevox_speak_player 工具用途 MCP应用程序 以在聊天中直接呈现交互式音频播放器。与标准不同 voicevox_speak 在服务器上播放音频的工具， 音频在客户端播放（在浏览器/应用程序中） --服务器上不需要音频设备。

特性

• 客户端播放 --音频在Claude Desktop的聊天中播放，而不是在服务器上播放。甚至可以通过远程连接工作。
• 播放/暂停控制 --对话中嵌入了完整的播放控制
• 多人对话 --通过曲目导航在一个播放器中顺序播放多个扬声器
• 扬声器切换 --直接从播放器UI更改任何片段的声音
• 片段编辑 --调整每个片段的速度、音量、语调、停顿时间和前后静音
• 重音短语编辑 --直接在UI中编辑重音位置和莫拉音高
• 添加/删除/重新排序分段 --拖放轨迹重新排序；内联添加新段
• WAV出口 --将所有曲目保存为编号的WAV文件，并自动打开输出文件夹
• 用户词典管理器 --通过预览播放添加、编辑和删除VOICEVOX用户词典单词
• 跨会话状态恢复 --玩家状态在服务器上持久化；重新打开聊天会恢复以前的曲目

按环境导出行为：

• Save and open 始终导出WAV文件。如果不支持打开文件资源管理器，导出仍然成功，保存路径显示在UI中。
• Choose output folder 在Windows/macOS上使用本机目录选择器。在不受支持的环境中，此操作将回退到默认导出目录。

支持的客户

注： speak_player 需要支持MCP应用程序的主机。在不支持MCP Apps的主机中，该工具不可用 speak （服务器端播放）可以代替。

玩家MCP工具

快速开始

需求

• Node.js 18.0.0或更高版本（或 包子) 或Docker
• VOICEVOX发动机 （必须正在运行；包含在Docker Compose中）
• ffplay（可选，推荐-Docker不需要）

安装FFplay

ffplay是FFmpeg附带的轻量级播放器，支持从stdin播放。如果可用，它会自动启用低延迟流媒体播放。

💡 FFplay是可选的。 如果没有它，播放将退回到基于临时文件的播放（Windows:PowerShell、macOS：afplay、Linux:aplay等）。

• 易于设置：每个操作系统安装一个衬垫（见以下步骤）
• 必修的： ffplay 必须在PATH中（安装后重新启动终端/应用程序）

FFplay Installation and PATH Setup

安装示例：

• Windows（其中任何一个）

- 翼： winget install --id=Gyan.FFmpeg -e - 巧克力： choco install ffmpeg - 勺： scoop install ffmpeg - 官方版本：从下载https://www.gyan.dev/ffmpeg/builds/或https://github.com/BtbN/FFmpeg-Builds并添加 bin 文件夹到PATH

• macOS

- 自制： brew install ffmpeg

• Linux

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

路径设置：

• Windows：添加 ...\ffmpeg\bin 到环境变量，然后重新启动PowerShell/终端和编辑器（Claude/VS代码等）

- 验证： powershell -c "$env:Path" 应包含ffmpeg路径

• macOS/Linux：通常自动检测。与核对 echo $PATH 如果需要，重新启动shell。
• MCP客户端（克劳德桌面/代码）：重新启动应用程序以重新加载PATH。

验证：

ffplay -version

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

3个步骤开始

1.启动VOICEVOX发动机

2.添加到Claude Desktop配置文件

配置文件位置：

• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "tts-mcp": {
      "command": "npx",
      "args": ["-y", "@kajidog/mcp-tts-voicevox"]
    }
  }
}

💡 如果使用Bun，只需更换 npx 和 bunx: ``json "command": "bunx", "args": ["@kajidog/mcp-tts-voicevox"] ``

3.重新启动克劳德桌面

就是这样！让克劳德“打个招呼”，它就会说话！

Docker快速入门

您可以使用Docker Compose通过单个命令运行MCP服务器和VOICEVOX引擎。无需安装Node.js或VOICEVOX。

1.启动容器

docker compose up -d

这将启动VOICEVOX引擎和MCP服务器（端口3000上的HTTP模式）。

2.添加到Claude Desktop配置文件（使用mcp-remote）

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

3.重新启动克劳德桌面

限制（Docker）： Docker容器没有音频设备，因此 voicevox_speak 默认情况下，工具（服务器端播放）处于禁用状态。使用 voicevox_speak_player 相反，它在客户端（在Claude Desktop中）播放音频，并且在服务器上没有任何音频设备的情况下工作。看 UI音频播放器 了解详情。

______________________________________________________________________

MCP工具

voicevox_speak --文本转语音

主要功能可从Claude调用。

示例：

// Simple text
{ "text": "Hello" }

// Specify speaker
{ "text": "Hello", "speaker": 3 }

// Different speakers per segment
{ "text": "1:Hello\n3:Nice weather today" }

// Wait for completion (synchronous processing)
{ "text": "Wait for this to finish before continuing", "waitForEnd": true }

Other Tools

______________________________________________________________________

配置

Environment Variables

VOICEVOX设置

回放选项

限制设置

限制AI指定某些选项。

禁用工具

# Disable individual tools
export VOICEVOX_DISABLED_TOOLS=speak_player,synthesize_file

# Disable a built-in group of tools
export VOICEVOX_DISABLED_GROUPS=player

# Combine groups and individual tools
export VOICEVOX_DISABLED_GROUPS=dictionary
export VOICEVOX_DISABLED_TOOLS=synthesize_file

内置群组 VOICEVOX_DISABLED_GROUPS / --disable-groups:

UI播放器设置

服务器设置

Command Line Arguments

命令行参数优先于环境变量。

# 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

Config File (.voicevoxrc.json)

您可以使用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"]
}

钥匙可以写在烤肉串里(use-streaming)，案例(useStreaming)，或内部密钥名称(defaultSpeaker).如果 .voicevoxrc.json 存在于当前目录中，它将自动加载。

HTTP Mode

对于远程连接：

启动服务器：

# 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桌面配置（使用mcp-remote）：

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

每个项目扬声器设置

使用Claude Code，您可以在中使用自定义标题为每个项目配置不同的默认扬声器 .mcp.json:

示例 .mcp.json:

{
  "mcpServers": {
    "tts": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-Voicevox-Speaker": "113",
        "X-API-Key": "your-api-key"
      }
    }
  }
}

这允许每个项目自动使用不同的语音字符。

优先级顺序：

1. 明确的 speaker 工具调用中的参数（最高）
2. 项目默认值来自 X-Voicevox-Speaker 头球
3. 全球 VOICEVOX_DEFAULT_SPEAKER 设置（最低）

WSL to Windows Host Connection

从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主机。

Using with ChatGPT

要与ChatGPT一起使用，请以HTTP模式将MCP服务器部署到云中，并访问VOICEVOX引擎。

1.部署到云端

使用Docker部署渲染、铁路等。（包括Dockerfile）。

2.设置VOICEVOX引擎

在本地运行VOICEVOX引擎，并通过ngrok公开它，或者将其与MCP服务器一起部署。

3.配置环境变量

4.在ChatGPT中添加连接器

转到ChatGPT设置→ 连接器→ 添加MCP服务器URL(https://your-app.onrender.com/mcp).

Using with Claude Web

基本步骤与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 值，单个实例不能同时为两个客户端提供服务。为每个实例部署单独的实例，或根据目标客户端切换环境变量。

______________________________________________________________________

故障排除

Audio is not playing

1.检查VOICEVOX发动机是否运行

curl http://localhost:50021/speakers

2.检查特定平台的播放工具

Not recognized by MCP client

• 检查软件包安装： npm list -g @kajidog/mcp-tts-voicevox
• 验证配置文件中的JSON语法
• 重新启动客户端

______________________________________________________________________

包结构

______________________________________________________________________

Developer Information

设置

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

命令

______________________________________________________________________

许可证

ISC