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 模型的相同許可證。