Claude Code Voice MCP Server

克劳德语音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)自动：

1. 检查系统要求（GPU、Docker等）
2. 安装所有依赖项（Docker、NVIDIA容器工具包、Python包）
3. 使用conda/venv设置Python环境
4. 为Kokoro TTS提取Docker镜像
5. 创建用于自动启动的systemd服务
6. 安装MCP服务器和CLI工具
7. 配置Claude桌面
8. 测试安装

手动安装（高级）

如果您更喜欢手动控制：

# 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 test

Claude桌面集成

安装后，重新启动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

可用声音

语音混合

通过混合多种声音创建自定义声音：

# 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=INFO

Claude桌面配置

安装程序会自动配置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 restart

API未响应

# 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 docker

Claude Desktop未显示MCP工具

1. 检查MCP服务器是否已配置： cat ~/.config/claude/claude_desktop_config.json
2. 完全重新启动克劳德桌面
3. 检查Claude Desktop日志是否有错误
4. 直接测试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)  │
└─────────────────┘

性能基准

RT=实时（1x=与音频长度相同的持续时间）

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

鸣谢

• 科科罗TTS:
• 原始Kokoro模型: 样式Bert-VITS2
• MCP框架: FastMCP

支持

对于问题、疑问或贡献：

• GitHub问题：\[你的仓库网址/问题\]
• 文档：有关开发人员指南，请参阅CLAUDE.md

路线图

• \[\]添加流媒体音频支持
• \[\]支持其他语言（日语、中文）
• \[\]从音频样本中克隆语音
• \[\]用于语音测试的Web UI
• \[\]实时语音变形
• \[\]与更多MCP客户端集成