克劳德语音TTS MCP服务器
使用高质量文本到语音MCP服务器 科科罗-82M 该型号（在TTS Arena中排名第一）支持语音混合和Claude Desktop集成。
特性
- 一流品质：Kokoro-82M在盲测中表现优于XTTS v2、MetaVoice、Fish Speech
- 快速：GPU加速时延迟100-300ms（实时35-100x）
- 语音混合：用自定义比率混合多个声音（例如。，
af_bella(2)+af_sky(1)) - MCP集成：与克劳德桌面/代码无缝集成
- GPU加速：支持NVIDIA CUDA，具有自动CPU回退功能
- 一个命令安装：自动安装程序处理一切
快速开始
# Clone or download this repository
git clone https://github.com/your-username/claude-code-voice-mcp-server.git
cd claude-code-voice-mcp-server
# Run the installer (handles everything automatically)
./install.sh
# Start the service
tts start
# Test it's working
tts test就是这样！MCP服务器现在可以在Claude Desktop中使用。
需求
- 操作系统：Linux（Ubuntu、Debian、Fedora、RHEL、Arch、SUSE）或macOS
- 图形处理器：配备CUDA 12.3+的NVIDIA GPU（推荐使用，CPU回退可用）
- 注意：macOS不支持NVIDIA GPU，将自动使用CPU
- 码头工人：如果丢失，将自动安装
- 磁盘：~4GB用于Docker镜像和模型
- 随机存取存储器：最低4GB，建议8GB
安装
安装程序(install.sh)自动：
- 检查系统要求（GPU、Docker等）
- 安装所有依赖项（Docker、NVIDIA容器工具包、Python包）
- 使用conda/venv设置Python环境
- 为Kokoro TTS提取Docker镜像
- 创建用于自动启动的systemd服务
- 安装MCP服务器和CLI工具
- 配置Claude桌面
- 测试安装
手动安装（高级）
如果您更喜欢手动控制：
# 1. Install dependencies (Debian/Ubuntu)
sudo apt-get update && sudo apt-get install -y docker.io python3 python3-pip
# Or Fedora/RHEL
# sudo dnf install -y docker python3 python3-pip
# Or Arch
# sudo pacman -Sy docker python python-pip
# Or macOS
# brew install docker python
# 2. Install NVIDIA Container Toolkit (Linux with NVIDIA GPU only)
# Debian/Ubuntu:
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://nvidia.github.io/libnvidia-container/stable/deb/\$(ARCH) /" | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker
# Fedora/RHEL:
# curl -s -L https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo | sudo tee /etc/yum.repos.d/nvidia-container-toolkit.repo
# sudo dnf install -y nvidia-container-toolkit
# sudo systemctl restart docker
# 3. Pull Docker image
docker pull ghcr.io/remsky/kokoro-fastapi-gpu:latest # GPU
# docker pull ghcr.io/remsky/kokoro-fastapi-cpu:latest # CPU
# 4. Start container
docker run -d --name claude-voice-tts --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest # GPU
# docker run -d --name claude-voice-tts -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest # CPU
# 5. Install MCP server
pip install uv
uv pip install -e .
# 6. Configure Claude Desktop
# Edit ~/.config/claude/claude_desktop_config.json
# Add claude-voice-tts MCP server configuration (see Configuration section)用法
服务控制
# Start/stop service
tts start
tts stop
tts restart
# Check status
tts status
# View logs
tts logs # Last 50 lines
tts logs -f # Follow logs
# Enable/disable auto-start
tts enable # Start on login
tts disable # Don't start on login
# Test service
tts testClaude桌面集成
安装后，重新启动Claude Desktop。MCP服务器自动提供以下工具：
generate_speech
通过可选的语音混合从文本生成语音。
参数：
text（必填）：文本转换为语音voice（可选）：语音名称或混合语音（默认值：af_bella)speed（可选）：语音速度0.5-2.0（默认值：1.0)output_format（可选）：音频格式：mp3、wav、opus（默认：mp3)save_to_file（可选）：保存到文件或返回base64（默认值：true)
例子：
Claude, generate speech saying "Hello, this is a test of voice blending" using a blend of af_bella and af_sky voices.list_voices
列出所有可用的语音和语音混合信息。
例子：
Claude, what voices are available?check_status
检查Kokoro TTS服务是否正在运行且可访问。
例子：
Claude, check if the TTS service is working.API直接使用
Kokoro TTS后端在端口8880上公开了一个与OpenAI兼容的API：
# List voices
curl http://localhost:8880/v1/audio/voices
# Generate speech
curl -X POST http://localhost:8880/v1/audio/speech \
-H "Content-Type: application/json" \
-d '{
"model": "kokoro",
"input": "Hello, this is a test.",
"voice": "af_bella",
"speed": 1.0,
"response_format": "mp3"
}' \
-o output.mp3
# Voice blending (2 parts Bella + 1 part Sky)
curl -X POST http://localhost:8880/v1/audio/speech \
-H "Content-Type: application/json" \
-d '{
"model": "kokoro",
"input": "Testing voice blending.",
"voice": "af_bella(2)+af_sky(1)",
"speed": 1.0
}' \
-o blended.mp3
# Play the audio
mpg123 output.mp3 # or ffplay output.mp3可用声音
| 声音 | 性别 | 口音 | 描述 |
|---|---|---|---|
af_bella | 女 | 美国人 | 贝拉 |
af_sky | 女 | 美国 | 天空 |
af_nicole | 女 | 美国人 | 妮可 |
am_adam | 男 | 美国人 | 亚当 |
am_michael | 男 | 美国人 | 迈克尔 |
bf_emma | 女 | 英国人 | Emma |
bf_isabella | 女 | 英国人 | 伊莎贝拉 |
bm_george | 男 | 英国人 | 乔治 |
bm_lewis | 男 | 英国人 | 刘易斯 |
语音混合
通过混合多种声音创建自定义声音：
# Syntax: voice1(weight1)+voice2(weight2)+...
af_bella(2)+af_sky(1) # 2 parts Bella, 1 part Sky
am_adam(3)+am_michael(1) # 3 parts Adam, 1 part Michael
bf_emma(1)+bf_isabella(1) # Equal mix of Emma and Isabella配置
环境变量
创建一个 .env 安装目录中的文件(~/.local/share/claude-code-voice-mcp-server/):
KOKORO_BASE_URL=http://localhost:8880
DEFAULT_VOICE=af_bella
DEFAULT_SPEED=1.0
OUTPUT_DIR=~/tts_output
TIMEOUT=30
LOG_LEVEL=INFOClaude桌面配置
安装程序会自动配置Claude Desktop，但您可以手动编辑 ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"claude-voice-tts": {
"command": "uv",
"args": [
"--directory",
"/home/USERNAME/.local/share/claude-code-voice-mcp-server",
"run",
"claude-voice-mcp"
],
"env": {
"KOKORO_BASE_URL": "http://localhost:8880"
}
}
}
}替换 USERNAME 使用您的实际用户名。
GPU与CPU性能
GPU（配备CUDA 12.3+的NVIDIA）
- 延迟：100-300ms
- 速度：35-100x实时
- 显存：~2-3GB
- 推荐：RTX 3060或更高版本
中央处理器
- 延迟：1-3.5秒
- 速度：\<1x实时
- 随机存取存储器：~4GB
- 作品：任何现代CPU
安装程序会自动检测您的硬件并使用适当的配置。
与其他服务共存
Kokoro TTS使用最少的资源，可以与其他GPU服务一起运行：
- 显存：~2-3GB（RTX 3090总共有24GB）
- 示例：同时运行Kokoro TTS+Whisper STT
- 端口：8880（可配置）
故障排除
服务无法启动
# Check Docker status
docker ps
systemctl --user status claude-voice-tts
# Check logs
tts logs
# Restart Docker
sudo systemctl restart docker
tts restartAPI未响应
# Test connection
curl http://localhost:8880/v1/audio/voices
# Check if port is in use
netstat -tulpn | grep 8880
# Restart service
tts restart未检测到GPU
# Check NVIDIA driver
nvidia-smi
# Test NVIDIA Container Toolkit
docker run --rm --gpus all nvidia/cuda:12.3.0-base-ubuntu22.04 nvidia-smi
# Reinstall toolkit
sudo apt-get install --reinstall nvidia-container-toolkit
sudo systemctl restart dockerClaude Desktop未显示MCP工具
- 检查MCP服务器是否已配置：
cat ~/.config/claude/claude_desktop_config.json - 完全重新启动克劳德桌面
- 检查Claude Desktop日志是否有错误
- 直接测试MCP服务器：
uv run claude-voice-mcp（应该开始时没有错误）
音频文件无法播放
# Install audio player
sudo apt-get install mpg123 ffmpeg
# Test playback
mpg123 ~/tts_output/your-file.mp3
ffplay ~/tts_output/your-file.mp3发展
在调试模式下运行MCP服务器
cd ~/.local/share/claude-code-voice-mcp-server
LOG_LEVEL=DEBUG uv run claude-voice-mcp运行测试
# Full test suite
pytest tests/
# Specific tests
pytest tests/test_mcp.py -v
# Coverage
pytest --cov=src tests/修改并重新加载
# Edit MCP server
vim ~/.local/share/claude-code-voice-mcp-server/src/claude_voice_mcp.py
# Restart Claude Desktop to reload MCP server
# Or test directly:
uv run claude-voice-mcp建筑
┌─────────────────┐
│ Claude Desktop │
│ (MCP Client) │
└────────┬────────┘
│ stdio
▼
┌─────────────────┐
│ MCP Server │
│ (claude_voice_mcp.py) │
└────────┬────────┘
│ HTTP
▼
┌─────────────────┐ ┌──────────────┐
│ Docker Container│◄──────┤ systemd │
│ Kokoro-FastAPI │ │ service │
│ (port 8880) │ └──────────────┘
└────────┬────────┘
│ GPU
▼
┌─────────────────┐
│ Kokoro-82M │
│ TTS Model │
│ (~2-3GB VRAM) │
└─────────────────┘性能基准
| 配置 | 延迟 | VRAM | 速度 |
|---|---|---|---|
| RTX 4090 GPU | 100毫秒 | 2.5 GB | 100倍RT |
| RTX 3090 GPU | 150毫秒 | 2.8 GB | 70倍RT |
| RTX 3060 GPU | 250毫秒 | 3.0GB | 40x RT |
| CPU（i7-12700） | 3.5秒 | N/A | 0.3倍RT |
| CPU（M3 Pro） | 1.0秒 | 不适用 | 1.0倍RT |
RT=实时（1x=与音频长度相同的持续时间）
许可证
MIT许可证-有关详细信息，请参阅许可证文件。
鸣谢
- 科科罗TTS:
- 原始Kokoro模型: 样式Bert-VITS2
- MCP框架: FastMCP
支持
对于问题、疑问或贡献：
- GitHub问题：\[你的仓库网址/问题\]
- 文档：有关开发人员指南，请参阅CLAUDE.md
路线图
- \[\]添加流媒体音频支持
- \[\]支持其他语言（日语、中文）
- \[\]从音频样本中克隆语音
- \[\]用于语音测试的Web UI
- \[\]实时语音变形
- \[\]与更多MCP客户端集成