Chatterbox MCP

🚀 Chatterbox TTS MCP Server

Chatterbox TTSモデルを使用して、自動再生付きのテキスト読み上げ機能を提供する、簡素化されたモデルコンテキストプロトコル（MCP）サーバーです。このサーバーは初回使用時に自動的にモデルを読み込み、プロセス全体を通じてリアルタイムの進捗通知を提供し、ユーザーに最新の情報を提供します。

🚀 クイックスタート

このMCPサーバーは、Chatterbox 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. モデル読み込みフェーズ:

   • "Loading Chatterbox TTS model..."
   • "Initializing PyTorch device..."
   • "Loading model weights..."
   • "Model loaded successfully!"

2. 音声生成フェーズ:

   • "Starting speech generation..."
   • "Speech generated, saving to temporary file..."

3. 再生フェーズ:

   • "Playing audio..."
   • "Audio playback completed!"

4. ステータス更新:

   • デバイス選択 (MPS/CUDA/CPU)
   • 該当する場合の音声プロンプトの使用
   • 成功/エラーメッセージ

📦 インストール

1. 依存関係のインストール:

   pip install mcp torch torchaudio
   

2. Chatterbox TTSのインストール: Chatterbox TTSのインストール手順に従って、chatterbox.ttsモジュールが利用可能になるようにしてください。

🔧 設定

オーディオファイルの保存先

デフォルトでは、サーバーはオーディオファイルを~/.chatterbox/audioに保存します。以下の方法でカスタム保存先を設定できます。

コマンドライン引数:

python chatterbox_mcp_server.py --audio-dir /path/to/custom/audio/directory

環境変数:

export CHATTERBOX_AUDIO_DIR="/path/to/custom/audio/directory"
python chatterbox_mcp_server.py

優先順位:

1. コマンドラインの--audio-dir引数 (最も高い優先順位)
2. CHATTERBOX_AUDIO_DIR環境変数
3. デフォルト: ~/.chatterbox/audio (最も低い優先順位)

オーディオファイルのTTL (Time To Live)

デフォルトでは、オーディオファイルは1時間後に自動的にクリーンアップされます。以下の方法でカスタムTTLを設定できます。

コマンドライン引数:

python chatterbox_mcp_server.py --audio-ttl-hours 24  # ファイルを24時間保持

環境変数:

export CHATTERBOX_AUDIO_TTL_HOURS=24
python chatterbox_mcp_server.py

優先順位:

1. コマンドラインの--audio-ttl-hours引数 (最も高い優先順位)
2. CHATTERBOX_AUDIO_TTL_HOURS環境変数
3. デフォルト: 1時間 (最も低い優先順位)

モデルの自動読み込み

デフォルトでは、起動時間を最小限に抑えるため、TTSモデルは初回使用時に読み込まれます。起動時に事前に読み込むことができます。

コマンドライン引数:

python chatterbox_mcp_server.py --auto-load-model

これにより、サーバー起動時にモデルが読み込まれ、数秒かかりますが、最初のTTSリクエストが高速化されます。

オーディオ保存機能:

• オーディオファイルは、自動クリーンアップを設定可能な永続的な保存先に保存されます
• ファイルはchatterbox://audio/{resource_id}リソースを通じてアクセス可能です
• ディレクトリが存在しない場合は自動的に作成されます
• 相対パス (展開されます) と~ホームディレクトリ表記をサポートします

💻 使用例

サーバーの起動

スタンドアロンでの起動:

python chatterbox_mcp_server.py

MCPツールとともに起動:

mcp dev chatterbox_mcp_server.py

Claude Desktopとの統合

Claude Desktopの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. 基本的なテキスト読み上げ:

   Please use the speak_text tool to say "Hello, welcome to the Chatterbox TTS demonstration!"
   

2. 表現力のある音声生成:

   Use speak_text to generate enthusiastic speech for "This is amazing!" with high expressiveness
   

このツールは自動的に以下の処理を行います:

• 必要に応じてモデルを読み込みます (進捗更新付き)
• 音声を生成します
• オーディオを再生します
• 一時ファイルをクリーンアップします
• 全体を通じてステータス更新を提供します

🔧 技術詳細

デバイスサポート

• Apple Silicon (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つのコマンドで音声を生成し再生します

トラブルシューティング

一般的な問題:

1. モデルの読み込みが遅い:

   • 初回読み込み時にモデルの重みがダウンロードされます
   • 進捗通知で現在の状態が表示されます
   • 2回目以降の使用ははるかに高速です

2. オーディオ再生の問題:

   • afplayコマンドはmacOS固有です
   • システムオーディオが正常に動作していることを確認してください
   • 音量設定を確認してください

3. メモリの問題:

   • モデルは大量のGPU/CPUメモリを必要とします
   • 読み込み中にシステムリソースを監視してください
   • 他のアプリケーションを閉じることを検討してください

4. デバイス選択:

   • サーバーは自動的に最適な利用可能なデバイスを選択します
   • 現在のデバイスに関する情報はモデル情報リソースを確認してください
   • MPS (Apple Silicon) > CUDA (NVIDIA) > CPU

📄 ライセンス

このMCPサーバーの実装は、基盤となるChatterbox TTSモデルと同じライセンスに従います。