麦克风语音合成引擎VOICEVOX

Name: 麦克风语音合成引擎VOICEVOX
Author: kajidog

作者：kajidog11 星标更新：2025-09-09

安装使用来源：spider==github.com

项目介绍

MCP TTS VOICEVOX

简体中文 | 日本語

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

特性

高级播放控制 - 通过队列管理、即时播放以及同步/异步控制实现灵活的音频处理
预取功能 - 预先生成下一个音频以实现平滑播放
跨平台支持 - 在 Windows、macOS 和 Linux（包括 WSL 环境中的音频播放）上运行
Stdio/HTTP 支持 - 支持 Stdio、SSE 和 StreamableHttp
多角色支持 - 每个片段指定独立的角色
自动文本分段 - 通过自动长文本分段实现稳定的音频合成
独立客户端库 - 提供为单独包的客户端库 @kajidog/voicevox-client

要求

Node.js 18.0.0 或更高版本
VOICEVOX 引擎或兼容引擎

安装

npm install -g @kajidog/mcp-tts-voicevox

使用方法

作为 MCP 服务器

1. 启动 VOICEVOX 引擎

启动 VOICEVOX 引擎并使其等待在默认端口 (http://localhost:50021)。

2. 启动 MCP 服务器

标准 I/O 模式（推荐）：

npx @kajidog/mcp-tts-voicevox

HTTP 服务器模式：

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

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

MCP 工具

`speak` - 文本转语音

将文本转换为语音并播放。

参数：

text: 字符串（多个文本由换行符分隔，角色规格为 "1:text" 格式）
speaker（可选）：角色ID
speedScale（可选）：播放速度
immediate（可选）：是否立即开始播放（默认值：true）
waitForStart（可选）：是否等待播放开始（默认值：false）
waitForEnd（可选）：是否等待播放结束（默认值：false）

示例：

// 简单文本
{ "text": "你好\n今天天气不错" }

// 角色规格
{ "text": "你好", "speaker": 3 }

// 每个片段指定角色
{ "text": "1:你好\n3:今天天气不错" }

// 即时播放（绕过队列）
{
  "text": "紧急消息",
  "immediate": true,
  "waitForEnd": true
}

// 等待播放完成（同步处理）
{
  "text": "等待此音频播放完成后进行下一步处理",
  "waitForEnd": true
}

// 添加到队列但不自动播放
{
  "text": "等待手动开始播放",
  "immediate": false
}

高级播放控制特性

即时播放 (`immediate: true`)

绕过队列立即播放音频：

与常规队列并行操作：不影响现有队列播放
多个同时播放：多个即时播放可以同时运行
适用于紧急通知：优先处理重要信息

同步播放控制 (`waitForEnd: true`)

等待播放完成以同步处理：

顺序处理：在音频播放后执行下一次处理
时间控制：使音频与其他处理协调
UI 同步：使屏幕显示与音频时间同步

// 示例 1：立即播放紧急消息并等待完成
{
  "text": "紧急！请立即检查",
  "immediate": true,
  "waitForEnd": true
}

// 示例 2：逐步音频指南
{
  "text": "步骤 1：请打开文件",
  "waitForEnd": true
}
// 下一步处理在上述音频完成后执行

其他工具

generate_query - 生成语音合成查询
synthesize_file - 生成音频文件
stop_speaker - 停止播放并清除队列
get_speakers - 获取角色列表
get_speaker_detail - 获取角色详情

包结构

@kajidog/mcp-tts-voicevox（此包）

MCP 服务器 - 与 Claude Desktop 等 MCP 客户端通信
HTTP 服务器 - 通过 SSE/StreamableHTTP 进行远程 MCP 通信

@kajidog/voicevox-client（独立包）

通用库 - 与 VOICEVOX 引擎通信的功能
跨平台 - 支持 Node.js 和浏览器环境
高级播放控制 - 即时播放、同步播放及队列管理功能

MCP 配置示例

Claude Desktop 配置

在你的 claude_desktop_config.json 文件中添加以下配置：

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

当需要 SSE 模式时

如果你需要在 SSE 模式下进行语音合成，你可以使用 mcp-remote 进行 SSE↔Stdio 转换：

Claude Desktop 配置

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

启动 SSE 服务器

Mac/Linux:

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

Windows:

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


## 环境变量

### VOICEVOX 配置

- `VOICEVOX_URL`: VOICEVOX 引擎 URL（默认值：`http://localhost:50021`）
- `VOICEVOX_DEFAULT_SPEAKER`: 默认角色ID（默认值：`1`）
- `VOICEVOX_DEFAULT_SPEED_SCALE`: 默认播放速度（默认值：`1.0`）

### 播放选项配置

- `VOICEVOX_DEFAULT_IMMEDIATE`: 是否在添加到队列时立即开始播放（默认值：`true`）
- `VOICEVOX_DEFAULT_WAIT_FOR_START`: 是否等待播放开始（默认值：`false`）
- `VOICEVOX_DEFAULT_WAIT_FOR_END`: 是否等待播放结束（默认值：`false`）

**使用示例：**

```bash
# 示例 1：等待所有音频播放完成（同步处理）
export VOICEVOX_DEFAULT_WAIT_FOR_END=true
npx @kajidog/mcp-tts-voicevox

# 示例 2：等待播放开始和结束
export VOICEVOX_DEFAULT_WAIT_FOR_START=true
export VOICEVOX_DEFAULT_WAIT_FOR_END=true
npx @kajidog/mcp-tts-voicevox

# 示例 3：手动控制（禁用自动播放）
export VOICEVOX_DEFAULT_IMMEDIATE=false
npx @kajidog/mcp-tts-voicevox
```

这些选项允许根据应用程序需求精细控制音频播放行为。

### 服务器配置

- `MCP_HTTP_MODE`: 启用 HTTP 服务器模式（设置为 `true` 启用）
- `MCP_HTTP_PORT`: HTTP 服务器端口号（默认值：`3000`）
- `MCP_HTTP_HOST`: HTTP 服务器主机（默认值：`0.0.0.0`）

## 使用 WSL（Windows 子系统 for Linux）

从 WSL 环境连接到 Windows 主机 MCP 服务器的配置方法。

### 1. Windows 主机配置

**使用 PowerShell 启动 MCP 服务器：**

```powershell
$env:MCP_HTTP_MODE='true'; $env:MCP_HTTP_PORT='3000'; npx @kajidog/mcp-tts-voicevox
```

### 2. WSL 环境配置

**检查 Windows 主机 IP 地址：**

```bash
# 从 WSL 获取 Windows 主机 IP 地址
ip route show | grep default | awk '{print $3}'
```

通常格式为 `172.x.x.1`。

**Claude Code .mcp.json 配置示例：**

```json
{
  "mcpServers": {
    "tts": {
      "type": "sse",
      "url": "http://172.29.176.1:3000/sse"
    }
  }
}
```

**重要事项：**
- 在 WSL 中，`localhost` 或 `127.0.0.1` 指向的是 WSL 内部，无法访问 Windows 主机服务
- 使用 WSL 网关 IP（通常是 `172.x.x.1`）来访问 Windows 主机
- 确保端口未被 Windows 防火墙阻止

**连接测试：**

```bash
# 从 WSL 检查连接到 Windows 主机 MCP 服务器
curl http://172.29.176.1:3000
```

如果正常，将返回 `404 Not Found`（因为根路径不存在）。

## 故障排除

### 常见问题

1. **VOICEVOX 引擎未运行**

   ```bash
   curl http://localhost:50021/speakers
   ```

2. **音频未播放**

   - 检查系统音频输出设备
   - 检查特定平台的音频播放工具：
     - **Linux**: 需要 `aplay`, `paplay`, `play`, `ffplay` 中的一个
     - **macOS**: `afplay`（已预安装）
     - **Windows**: PowerShell（已预安装）

3. **未被 MCP 客户端识别**
   - 检查包安装情况：`npm list -g @kajidog/mcp-tts-voicevox`
   - 检查配置文件中的 JSON 语法

## 许可证

ISC

[![MseeP.ai 安全评估徽章](https://gips1.baidu.com/it/u=1336182088,4063755587&fm=3081&app=3081&f=PNG?w=461&h=180)](https://mseep.ai/app/kajidog-mcp-tts-voicevox)

## 开发者信息

本地开发此仓库的说明。

### 设置

1. 克隆仓库：
   ```bash
   git clone https://github.com/kajidog/mcp-tts-voicevox.git
   cd mcp-tts-voicevox
   ```
2. 安装 [pnpm](https://pnpm.io/)（如果尚未安装）。
3. 安装依赖项：
   ```bash
   pnpm install
   ```

### 主要开发命令

你可以在项目根目录运行以下命令。

- **构建所有包：**
  ```bash
  pnpm build
  ```
- **运行所有测试：**
  ```bash
  pnpm test
  ```
- **运行所有代码检查器：**
  ```bash
  pnpm lint
  ```
- **在开发模式下启动根服务器：**
  ```bash
  pnpm dev
  ```
- **在开发模式下启动 stdio 接口：**
  ```bash
  pnpm dev:stdio
  ```

这些命令还将正确处理工作区内的相关包的处理。