Resemble AI音声生成MCPサーバー

モデル コンテキスト プロトコル (MCP) を使用してClaudeおよびCursorと統合するResemble AI音声生成 API のサーバー実装。

特徴

• Resemble AIの音声を使用してテキストから音声を生成する

• 利用可能な音声モデルの一覧

• オーディオをローカルファイルまたはbase64でエンコードされた文字列として返します

• 複数の接続方法:

  • SSE トランスポート- ネットワークベースのサーバー送信イベント (デフォルト)

  • StdIOトランスポート- 直接プロセス通信

Related MCP server: MCP Sound Tool

セットアップ手順

前提条件

• Python 3.10以上

• Resemble AI APIキー（ Resemble AIでサインアップ）

環境設定

オプション 1: Conda を使用する (推奨)

# Run the setup script
./scripts/setup_environment.sh

# Activate the environment
conda activate resemble_mcp

オプション2: 仮想環境の使用

# Run the setup script
./scripts/setup_venv.sh

# Activate the environment
source venv/bin/activate

構成

Resemble AI API キーを環境変数として設定します。

export RESEMBLE_API_KEY="your_api_key_here"

または、プロジェクト ルートに次の内容の.envファイルを作成します。

RESEMBLE_API_KEY=your_api_key_here

サーバーの実行

実行スクリプトの使用（推奨）

希望する実装を選択してください:

# Run the MCP SDK implementation with SSE transport (default)
./run_server.sh mcp 8083

# Run the HTTP implementation
./run_server.sh http 8083

# Run with StdIO transport (for direct process communication)
./run_server.sh stdio

CLIを直接使用する

# Run the MCP SDK implementation with SSE transport
python -m src.cli --implementation mcp --port 8083

# Run with StdIO transport
python -m src.cli --implementation stdio

Claudeデスクトップに接続しています

SSEトランスポート接続

claude_desktop_config.jsonファイルを作成します。

{
  "mcpServers": {
    "resemble-ai": {
      "sseUrl": "http://localhost:8083/sse"
    }
  }
}

StdIOトランスポート接続

claude_desktop_config.jsonファイルを作成します。

{
  "mcpServers": {
    "resemble-ai": {
      "command": "python",
      "args": ["-m", "src.cli", "--implementation", "stdio"],
      "env": {
        "RESEMBLE_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

カーソルに接続

SSEトランスポート接続

1. 設定→AI→MCPサーバーへ移動

2. 「サーバーを追加」をクリックします

3. 接続タイプとして「SSE」を選択します

4. URLを次のように設定します: http://localhost:8083/sse

StdIOトランスポート接続

1. 設定→AI→MCPサーバーへ移動

2. 「サーバーを追加」をクリックします

3. 接続タイプとして「サブプロセス」を選択します

4. コマンドを次のように設定します: python -m src.cli --implementation stdio

5. オプションで環境変数を追加します。

   • RESEMBLE_API_KEY : Resemble AI APIキー

利用可能なツール

list_voices

Resemble AI から利用可能な音声モデルを一覧表示します。

generate_tts

テキストから音声オーディオを生成します。

パラメータ:

• text : 音声に変換するテキスト

• voice_id : 使用する音声のID

• return_type : オーディオを返す方法: 'file' または 'base64' (オプション、デフォルト: 'file')

• output_filename : 拡張子なしの出力ファイル名（オプション）

実装の詳細

このプロジェクトにはいくつかの実装が含まれています。

• src/resemble_mcp_server.py : SSEトランスポートでMCP SDKを使用する

• src/resemble_stdio_server.py : 直接プロセス通信に StdIO トランスポートを使用する

• src/resemble_http_server.py : SSE を使用した HTTP 実装 (フォールバック)

• src/resemble_ai_server.py : 直接API実装

• src/resemble_ai_sdk_server.py : 公式 Resemble SDK を使用した実装

トラブルシューティング

MCP SDK インポートエラー

MCP SDK のインポート中に問題が発生した場合、サーバーは自動的に SSE トランスポートを使用した HTTP 実装にフォールバックします。

接続の問題

Claude または Cursor がサーバーに接続できない場合:

1. サーバーが稼働していることを確認する

2. 正しいURLが設定されていることを確認する

3. APIキーが有効であることを確認してください

4. サーバーログでエラーを探す

StdIO と SSE トランスポート

• サーバーを別々に、または別のマシンで実行する場合は**、SSEトランスポート**を使用します。

• Claude/Cursor にサーバープロセスを管理させたい場合は、 StdIO トランスポートを使用します。

例

使用例はexamples/ディレクトリにあります。

📁 リポジトリ構造

.
├── src/                 # Source code for the server implementations
│   ├── resemble_mcp_server.py    # MCP SDK implementation (recommended)
│   ├── resemble_http_server.py   # HTTP API implementation
│   ├── resemble_ai_server.py     # Direct API implementation
│   ├── resemble_ai_sdk_server.py # Resemble SDK implementation
│   └── cli.py           # CLI tool for running the server
├── tests/               # Test scripts
├── docs/                # Documentation
├── examples/            # Example usage and tools
├── scripts/             # Setup and utility scripts
├── output/              # Generated audio output directory
├── .env.example         # Example environment configuration
├── requirements.txt     # Python dependencies
└── README.md            # This file

🚀 クイックセットアップ

インストールを簡単にするために、次の 2 つのセットアップ スクリプトが提供されています。

Conda の使用 (推奨)

# Make the script executable
chmod +x scripts/setup_environment.sh

# Run the setup script
./scripts/setup_environment.sh

Python venvの使用

# Make the script executable
chmod +x scripts/setup_venv.sh

# Run the setup script
./scripts/setup_venv.sh

どちらのスクリプトでも次のようになります。

1. Python 3.10以上の環境を作成する

2. 必要な依存関係をすべてインストールする

3. テンプレート.envファイルを設定する

4. オーディオファイルの出力ディレクトリを作成する

手動インストール

手動で設定する場合:

1. Python 3.10 以降の環境を作成します。

   # Using conda
   conda create -n resemble_mcp python=3.10
   conda activate resemble_mcp
   
   # OR using venv (with Python 3.10+ already installed)
   python3.10 -m venv venv
   source venv/bin/activate

2. 依存関係をインストールします:

   pip install uvicorn fastapi python-dotenv requests pydantic httpx sse-starlette
   pip install git+https://github.com/modelcontextprotocol/python-sdk.git

3. 環境変数を設定します。

   cp .env.example .env

   .envファイルを編集し、Resemble AI API キーを追加します。

   RESEMBLE_API_KEY=your_api_key_here

   オプション: オーディオ出力設定をカスタマイズする

   OUTPUT_DIR=./output
   AUDIO_FORMAT=mp3

4. 出力ディレクトリを作成します:

   mkdir -p output

🚀 サーバーの実行

すべての実装をサポートする新しい CLI ツールを使用してサーバーを実行できます。

# Activate your environment if not already activated
conda activate resemble_mcp
# OR
source venv/bin/activate

# Run the MCP SDK implementation (recommended)
python -m src.cli --implementation mcp --port 8083

# Other implementations:
# HTTP API implementation
python -m src.cli --implementation http --port 8083
# Direct API implementation
python -m src.cli --implementation direct --port 8083
# Resemble SDK implementation
python -m src.cli --implementation sdk --port 8083

🔌 カーソルAIとの統合

Cursor は、SSE インターフェースを介して Resemble AI 音声生成サーバーと対話できます。

1. カーソルで設定→AI→MCPサーバーへ移動します。

2. 「サーバーを追加」をクリックし、SSE URL を入力します: http://localhost:8083/sse (必要に応じてポートを調整してください)

3. 設定を保存する

🔌 Claude Desktopとの統合

1. Claude Desktop 設定で MCP サーバーを構成します。

   {
     "mcpServers": {
       "resemble-ai": {
         "command": "python",
         "args": ["-m", "src.cli", "--implementation", "mcp"],
         "env": {
           "RESEMBLE_API_KEY": "your_api_key_here"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }

🛠️ ツールのドキュメント

リストの声

Resemble AI から利用可能なすべての音声モデルを一覧表示します。

**パラメータ:**なし

戻り値:

• voices : 利用可能な音声モデルのリスト（ID、名前、性別、言語、アクセント、説明付き）

生成TTS

テキストから音声オーディオを生成します。

パラメータ:

• text （文字列、必須）: 音声に変換するテキスト

• voice_id （文字列、必須）: 使用する音声のID

• return_type (文字列、オプション): オーディオを返す方法: 'file' または 'base64' (デフォルト: 'file')

• output_filename (文字列、オプション): 拡張子なしの出力ファイル名 (デフォルト: 自動生成された名前)

戻り値:

• success (ブール値): 操作が成功したかどうか

• message (文字列): ステータスメッセージ

• audio_data (文字列、オプション): Base64でエンコードされたオーディオデータ（return_typeが 'base64'の場合）

• file_path (文字列、オプション): 保存されたオーディオファイルへのパス (return_type が 'file' の場合)

💬 プロンプトの例

Cursor または Claude Desktop に接続すると、次のようなプロンプトを使用できます。

利用可能な音声の一覧:

List all available voice models from Resemble AI.

音声オーディオの生成:

Generate audio of the text "Hello, this is a test of the Resemble AI voice generation system" using a male English voice.

⚠️ トラブルシューティング

• Pythonバージョンの問題：MCPパッケージにはPython 3.10以降が必要です。提供されているセットアップスクリプトを使用して適切な環境を構築してください。

• API接続の問題：正しいAPIエンドポイントを使用していることを確認してください。Resemble AI APIエンドポイントはhttps://app.resemble.ai/api/v2/です。

• 認証エラー: API キーが正しく、期限切れでないことを確認してください。

• プロジェクトが不足しています：APIを使用するには、Resembleアカウントに少なくとも1つのプロジェクトが必要です。必要に応じて、Resemble AIダッシュボードからプロジェクトを作成してください。

• カーソル SSE 接続エラー: カーソルが SSE 経由で接続できない場合は、次の点を確認してください。

  • サーバーは指定されたポートで実行されています

  • 正しい/sseエンドポイントを使用しています

  • ファイアウォールが接続をブロックしていない

  • サーバーとカーソルの両方を再起動してみてください

📚 追加ドキュメント

より詳細なドキュメントについては、 docs/ディレクトリ内のファイルを参照してください。

📄 ライセンス

マサチューセッツ工科大学