内容
# AllTalk 文字转语音 MCP 服务器
一个为 AllTalk 文字转语音（TTS）提供的模型上下文协议（MCP）服务器，具有全功能的文本转语音功能，支持 RVC 语音转换、旁白模式和高级音频生成。
## 功能特点
- **支持全功能 AllTalk API**：包含 SillyTavern 的 AllTalk 集成的所有参数
- **RVC 语音转换**：实时语音克隆，支持 GPU 加速
- **旁白模式**：为角色对话和旁白提供独立的语音
- **多种输出格式**：支持 WAV 音频，参数可配置
- **性能优化**：支持 DeepSpeed 和低显存模式
- **跨平台音频播放**：生成后自动播放音频
## 环境要求
1. **AllTalk TTS 服务器**：需在本地或远程运行
- 默认地址：`http://localhost:7851`
- [AllTalk GitHub 地址](https://github.com/erew123/alltalk_tts)
2. **Python 3.8+**，需支持虚拟环境
3. **音频系统**：PulseAudio、ALSA 或兼容的音频后端
## 安装步骤
### 1. 克隆代码仓库
```bash
git clone https://github.com/yourusername/alltalk-tts-mcp.git
cd alltalk-tts-mcp
```
### 2. 配置 Python 环境
#### 选项 A：使用 uv（推荐 - 更快）
```bash
# 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或使用 pip 安装：pip install uv
# 创建虚拟环境并安装依赖
uv sync
```
#### 选项 B：使用 pip（传统方式）
```bash
python -m venv .venv
source .venv/bin/activate # Windows 下使用：.venv\Scripts\activate
pip install -r requirements.txt
```
### 3. 配置环境变量
创建 `.env` 文件或设置环境变量：
```bash
# 必需：AllTalk 服务器 URL
export ALLTALK_URL="http://localhost:7851"
# 可选：音频播放设置
export PULSE_SERVER="unix:/run/user/$(id -u)/pulse/native"
export XDG_RUNTIME_DIR="/run/user/$(id -u)"
```
## 配置
### Claude Desktop（`~/.config/claude/desktop-config.json` 或 `~/.mcp.json`）
```json
{
"mcpServers": {
"alltalk-tts": {
"command": "/path/to/alltalk-tts-mcp/.venv/bin/python",
"args": ["/path/to/alltalk-tts-mcp/server.py", "--transport", "stdio"],
"env": {
"ALLTALK_URL": "http://localhost:7851",
"PULSE_SERVER": "unix:/run/user/1000/pulse/native",
"XDG_RUNTIME_DIR": "/run/user/1000"
}
}
}
}
```
### OpenCode（`~/.config/opencode/opencode.json`）
```json
{
"mcp": {
"alltalk-tts": {
"type": "local",
"command": [
"/path/to/alltalk-tts-mcp/.venv/bin/python",
"/path/to/alltalk-tts-mcp/server.py",
"--transport",
"stdio"
],
"environment": {
"ALLTALK_URL": "http://localhost:7851",
"PULSE_SERVER": "unix:/run/user/1000/pulse/native",
"XDG_RUNTIME_DIR": "/run/user/1000"
},
"enabled": true
}
}
}
```
## 可用工具
### 核心 TTS 生成
- `generate_tts` - 全功能 TTS，包含所有参数
- `quick_tts` - 简化 TTS，支持 RVC
- `generate_with_rvc` - TTS，支持 RVC 语音转换
- `generate_narrator` - TTS，支持旁白模式
- `stream_tts` - 实时流式 TTS（不支持 RVC/旁白）
### 配置与信息
- `list_voices` - 列出可用的 TTS 语音
- `list_rvc_voices` - 列出可用的 RVC 模型
- `get_current_settings` - 获取当前的 AllTalk 配置
- `switch_model` - 切换 TTS 模型
- `set_deepspeed` - 启用/禁用 DeepSpeed 优化
- `set_low_vram` - 启用/禁用低显存模式
## 使用示例
### OpenCode 风格
```bash
# 列出可用语音
alltalk-tts_list_voices
# 生成 TTS，支持 RVC
alltalk-tts_generate_tts \
--text_input "Hello, this is a test" \
--character_voice_gen "female_01.wav" \
--rvccharacter_voice_gen "" \
--autoplay true
# 快速 TTS 生成
alltalk-tts_quick_tts \
--text "Quick test" \
--voice "male_01.wav" \
--rvc_model "eminem/eminem-new-era-v2-48k.pth"
```
### Claude 代码风格
```python
# 在 Claude 中使用 MCP 工具
voices = alltalk_tts.list_voices()
print(voices)
# 生成 TTS，指定参数
result = alltalk_tts.generate_tts(
text_input="Hello from Claude!",
character_voice_gen="female_01.wav",
narrator_enabled=True,
narrator_voice_gen="male_01.wav",
rvccharacter_voice_gen="",
speed=1.2,
pitch=2
)
print(f"Generated: {result}")
```
### 高级示例：旁白模式
```python
result = alltalk_tts.generate_narrator(
text="\"Hello,\" said the character. The narrator continued the story.",
character_text="Hello,",
character_voice="female_01.wav",
narrator_voice="male_01.wav",
language="auto"
)
```
## 参数参考
### `generate_tts` 参数：
- `text_input`（必需）：待合成的文本
- `character_voice_gen`：角色语音文件（默认："female_01.wav"）
- `narrator_enabled`：启用旁白模式（默认：false）
- `narrator_voice_gen`：旁白语音（默认："male_01.wav"）
- `rvccharacter_voice_gen`：角色 RVC 模型（默认："")
- `rvccharacter_pitch`：RVC 音调偏移（-24 至 24，默认：0）
- `language`：语言代码或 "auto"（默认："auto"）
- `speed`：语音速度（0.25-2.0，默认：1.0）
- `pitch`：语音音调调整（-10 至 10，默认：0）
- `temperature`：采样温度（0.1-1.0，默认：0.8）
- `autoplay`：生成后自动播放（默认：true）
## 故障排除
### 音频播放问题
1. **生成后无声音**：检查音频系统和权限
```bash
# 测试音频系统
paplay --version
# 检查 PulseAudio 套接字
ls -la /run/user/$(id -u)/pulse/
```
2. **权限错误**：确保用户有权访问音频系统
```bash
groups | grep audio
sudo usermod -a -G audio $USER
```
### API 连接问题
1. **AllTalk 服务器无响应**：验证服务器是否运行
```bash
curl http://localhost:7851/api/voices
```
2. **GPU 未利用**：检查 RVC 参数和 GPU 驱动
```bash
nvidia-smi # 用于 NVIDIA GPU
```
### MCP 集成问题
1. **工具未显示**：检查 MCP 配置文件语法
2. **连接错误**：验证 Python 路径和虚拟环境
3. **超时错误**：在 MCP 客户端配置中增加超时时间
## 开发
### 自定义配置
要创建自定义配置：
1. **克隆代码仓库**：
```bash
git clone https://github.com/bpawnzZ/alltalk-tts-mcp.git
cd alltalk-tts-mcp
```
2. **设置环境**：
```bash
uv sync # 或使用 pip：python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
```
3. **为您的系统配置**：
- 编辑 `server.py` 以更改默认值（语音、RVC 模型等）
- 为您的 AllTalk 服务器 URL 设置环境变量
- 使用您的特定路径更新 MCP 客户端配置
4. **常见自定义**：
- 更改 `ALLTALK_URL` 为您的服务器地址
- 在 `server.py` 参数中修改默认语音
- 设置您偏好的 RVC 模型
- 为您的系统调整音频播放设置
### 测试
```bash
# 直接测试服务器
python server.py --help
# 使用 stdio 传输（适用于 MCP 客户端）
python server.py --transport stdio
# 使用 SSE 传输（适用于 HTTP 客户端）
python server.py --transport sse --host 0.0.0.0 --port 8080
```
### 添加新功能
1. 从 `main` 分支创建功能分支
2. 在 `server.py` 中实现更改
3. 更新文档
4. 使用 OpenCode 和 Claude Desktop 进行测试
5. 合并到相应分支
## 许可证
MIT 许可证 - 参见 LICENSE 文件了解详情。
## 致谢
- [AllTalk TTS](https://github.com/erew123/alltalk_tts) 提供优秀的 TTS 引擎
- [模型上下文协议](https://spec.modelcontextprotocol.io/) 提供协议规范
- Claude Desktop 和 OpenCode 提供 MCP 客户端实现
