使用说明

克劳德语音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 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

可用声音

声音	性别	口音	描述
`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=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工具

检查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: github/remsky/Kokoro-FastAPI
原始Kokoro模型: 样式Bert-VITS2
MCP框架: FastMCP

支持

对于问题、疑问或贡献：

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

路线图

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

使用说明

克劳德语音TTS MCP服务器

特性

快速开始

需求

安装

手动安装（高级）

用法

服务控制

Claude桌面集成

generate_speech

list_voices

check_status

API直接使用

可用声音

语音混合

配置

环境变量

Claude桌面配置

GPU与CPU性能

GPU（配备CUDA 12.3+的NVIDIA）

中央处理器

与其他服务共存

故障排除

服务无法启动

API未响应

未检测到GPU

Claude Desktop未显示MCP工具

音频文件无法播放

发展

在调试模式下运行MCP服务器

运行测试

修改并重新加载

建筑

性能基准

许可证

鸣谢

支持

路线图

相关 MCP

多模态生成API服务

Hugging Face MCP服务器

语音处理服务

macOS通知服务

短视频生成工具

文本转语音服务

`generate_speech`

`list_voices`

`check_status`