chatterbox-mcp

🚀 聊天宝文本转语音MCP服务器

这是一个简化版的模型上下文协议（MCP）服务器，借助聊天宝文本转语音（TTS）模型，它能够实现文本转语音功能，并自动播放生成的语音。服务器会在首次使用时自动加载模型，还能提供实时进度通知，让用户随时了解处理过程。

🚀 快速开始

此MCP服务器通过一个简洁的工具，将聊天宝TTS的功能开放出来，实现从文本生成语音并自动播放。服务器能够无缝处理模型加载、进度报告、临时文件管理和音频播放等任务。

✨ 主要特性

单一工具：speak_text

speak_text 工具提供了完整的文本转语音功能：

• 参数：

  • text（必填）：需要转换为语音的文本
  • exaggeration（可选）：控制语音表现力（范围为 0.0 - 1.0，默认值为 0.5）
  • cfg_weight（可选）：控制无分类器引导（范围为 0.0 - 1.0，默认值为 0.5）

• 特性：

  • 自动加载模型并提供进度通知
  • 使用临时文件生成语音（自动清理）
  • 在 macOS 系统上使用 afplay 自动播放音频
  • 在各个阶段提供实时进度更新：
    • 模型初始化和加载
    • 语音生成
    • 音频播放

资源：chatterbox://model-info

获取 TTS 模型状态和设备能力的相关信息：

• 模型加载状态（已加载/未加载）
• 设备信息（MPS/CUDA/CPU）
• 硬件加速可用性

📦 安装指南

1. 安装依赖项：

   pip install mcp torch torchaudio
   

2. 安装聊天宝 TTS： 按照聊天宝 TTS 的安装说明进行操作，确保 chatterbox.tts 模块可用。

💻 使用示例

运行服务器

独立运行：

python chatterbox_mcp_server.py

与 MCP 工具一起运行：

mcp dev chatterbox_mcp_server.py

与 Claude 桌面端集成

添加到你的 Claude 桌面端 MCP 配置中：

基本配置：

{
  "mcpServers": {
    "chatterbox-tts": {
      "command": "python",
      "args": ["/path/to/chatterbox_mcp_server.py"],
      "env": {}
    }
  }
}

自定义配置：

{
  "mcpServers": {
    "chatterbox-tts": {
      "command": "python",
      "args": [
        "/path/to/chatterbox_mcp_server.py", 
        "--audio-dir", "/custom/audio/path",
        "--auto-load-model",
        "--audio-ttl-hours", "24"
      ],
      "env": {
        "CHATTERBOX_AUDIO_DIR": "/custom/audio/path",
        "CHATTERBOX_AUDIO_TTL_HOURS": "24"
      }
    }
  }
}

从大语言模型（LLM）调用的示例

1. 基本文本转语音：

   请使用 speak_text 工具说出“你好，欢迎来到聊天宝 TTS 演示！”
   

2. 富有表现力的语音：

   使用 speak_text 工具为“这太棒了！”生成富有激情的语音
   

该工具将自动完成以下操作：

• 必要时加载模型（提供进度更新）
• 生成语音
• 播放音频
• 清理临时文件
• 全程提供状态更新

🔧 技术细节

设备支持

• 苹果硅芯片（M1/M2/M3/M4）：在可用时使用 MPS 加速
• NVIDIA GPU：在可用时使用 CUDA
• CPU 备用方案：可在任何系统上运行

音频处理

• 使用临时文件存储音频
• 播放后自动清理
• 输出 WAV 格式
• 生成高质量音频

模型管理

• 模型在首次使用时加载一次
• 供所有后续请求共享使用
• 线程安全加载并跟踪进度
• 自动检测和优化设备

📚 详细文档

文件结构

chatterbox-mcp/
├── chatterbox_mcp_server.py    # MCP 服务器实现
└── README.md                   # 本说明文档

开发

此版本的主要改进

1. 简化接口：使用单一的 speak_text 工具，而非多个工具
2. 自动播放：无需手动播放生成的文件
3. 进度通知：实时更新模型加载和生成进度
4. 持久音频存储：存储音频文件，并可配置自动清理
5. 更好的错误处理：全面的错误报告和恢复机制
6. 简化工作流程：一条命令即可生成并播放语音

故障排除

常见问题：

1. 模型加载缓慢：

   • 首次加载时会下载模型权重
   • 进度通知会显示当前状态
   • 后续使用会快很多

2. 音频播放问题：

   • afplay 命令仅适用于 macOS 系统
   • 确保系统音频正常工作
   • 检查音量设置

3. 内存问题：

   • 模型需要大量的 GPU/CPU 内存
   • 加载时监控系统资源
   • 考虑关闭其他应用程序

4. 设备选择：

   • 服务器会自动选择最佳可用设备
   • 查看模型信息资源以了解当前设备
   • MPS（苹果硅芯片）> CUDA（NVIDIA）> CPU

📄 许可证

此 MCP 服务器的实现遵循底层聊天宝 TTS 模型的相同许可证。