Hunyuan Image Replicate MCP Server

🚀 Hunyuan Image Replicate MCP Server

このプロジェクトは、Replicateプラットフォームを介してHunyuan Imageモデルを使用し、画像生成機能を提供するModel Context Protocol (MCP) サーバーです。

✨ 主な機能

Hunyuan Imageは、高度なテキストから画像への基礎モデルで、以下の点で優れています。

• 卓越した能力：Hunyuan Image 2.1は、テキストの感情を表現する画像を生成します。
• 高品質な画像生成：詳細なテキストプロンプトから高品質な画像を生成します。
• 複数の画像サイズとアスペクト比のサポート
• 高度なガイダンス制御：結果を微調整するための高度なガイダンス制御が可能です。
• 再現可能な生成：シードをサポートし、再現可能な生成ができます。
• バッチ生成：一度に最大4枚の画像を生成できます。

📦 インストール

前提条件

1. Replicate APIトークン：Replicate からAPIトークンを取得します。

   • https://replicate.com/ でアカウントを登録します。
   • アカウント設定に移動し、APIトークンを生成します。
   • このトークンは設定に必要なので、安全に保管してください。

2. Node.js：Node.js（バージョン18以上）がインストールされていることを確認してください。

クイックセットアップ（推奨）

このサーバーを使用する最も簡単な方法は、npxを通じることです。npxは自動的に最新バージョンをダウンロードして実行します。

Claudeデスクトップアプリの場合

サーバーをClaudeデスクトップの設定ファイルに追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hunyuan-image": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/hunyuan-image-replicate-mcp-server.git"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "your_replicate_api_token_here"
      }
    }
  }
}

Kilo Code MCP設定の場合

以下のMCP設定ファイルに追加します。 C:\Users\[username]\AppData\Roaming\Code\User\globalStorage\kilocode.kilo-code\settings\mcp_settings.json

{
  "mcpServers": {
    "hunyuan-image": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/hunyuan-image-replicate-mcp-server.git"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "your_replicate_api_token_here"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

npx設定の利点

✅ 汎用性：Node.jsがインストールされた任意のマシンで動作します。 ✅ ローカルインストール不要：npxが自動的にダウンロードして実行します。 ✅ 常に最新バージョン：GitHubリポジトリから最新バージョンを取得します。 ✅ クロスプラットフォーム：Windows、macOS、Linuxで互換性があります。 ✅ 設定同期：MCPクライアントを使用するすべての場所で動作します。

手動インストール（代替方法）

ローカルにインストールする場合は、以下の手順を実行します。

1. リポジトリをクローンする

   git clone https://github.com/PierrunoYT/hunyuan-image-replicate-mcp-server.git
   cd hunyuan-image-replicate-mcp-server
   

2. 依存関係をインストールする

   npm install
   

3. サーバーをビルドする

   npm run build
   

4. 設定で絶対パスを使用する

   {
     "mcpServers": {
       "hunyuan-image": {
         "command": "node",
         "args": ["/absolute/path/to/hunyuan-image-replicate-mcp-server/build/index.js"],
         "env": {
           "REPLICATE_API_TOKEN": "your_replicate_api_token_here"
         }
       }
     }
   }
   

絶対パスを取得するヘルパースクリプト

npm run get-path

💻 使用例

設定が完了したら、MCPクライアントを通じてサーバーを使用できます。

基本的な使用法

Generate an image of a serene mountain landscape at sunset with a lake reflection

高度な使用法

Create a cartoon consisting of four panels, arranged in a 2x2 grid, depicting a chameleon's dilemma with vibrant colors and clean lines

特定の画像サイズ

Generate a portrait-oriented image of a futuristic cityscape (896x1152)

高品質な生成

Generate a photorealistic portrait with 50 inference steps and guidance scale 10

高度なパラメータ

Create a detailed fantasy landscape with seed 12345 for reproducibility and generate 2 variations

📚 ドキュメント

利用可能なツール

generate_image

Replicateを介してHunyuan Imageを使用し、テキストプロンプトから高品質な画像を生成します。

パラメータ：

• prompt（必須）：生成する画像のテキスト説明（詳細なプロンプトをサポート）
• image_size（オプション）：画像サイズ - 以下のいずれか：1024x1024, 1152x896, 896x1152, 1216x832, 832x1216, 1344x768, 768x1344, 1536x640, 640x1536（デフォルト：1024x1024）
• num_outputs（オプション）：生成する画像の数（1 - 4、デフォルト：1）
• num_inference_steps（オプション）：デノイジングステップの数（1 - 100、デフォルト：25）
• guidance_scale（オプション）：プロンプトへの忠実度を制御します。数値が高いほど厳格になります（1 - 20、デフォルト：7.5）
• seed（オプション）：再現可能な結果を得るための乱数シード

APIレスポンス形式

サーバーは生成された画像に関する詳細情報を返します。

✅ Successfully generated 1 image(s) using Hunyuan Image:

📝 **Generation Details:**
• Prompt: "a serene mountain landscape at sunset"
• Image Size: 1024x1024
• Number of Images: 1
• Inference Steps: 25
• Guidance Scale: 7.5
• Seed Used: 1234567890
• Generation Time: 4500ms

🖼️ **Generated Images (1 total, 1 downloaded):**
• Image 1: ./images/hunyuan_image_mountain_landscape_0_2024-01-15T10-30-45.webp (https://replicate.delivery/...)

💾 Images have been downloaded to the local 'images' directory.

開発

ローカルテスト

# Test the server directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js

ウォッチモード

npm run watch

テストサーバーを実行

npm run test:server

ヘルスチェック

npm run health-check

インスペクターツール

npm run inspector

環境変数

必須

• REPLICATE_API_TOKEN：ReplicateのAPIトークン（画像生成に必要）

オプション

• NODE_ENV：環境モード（development, production, test） - デフォルト：production
• LOG_LEVEL：ログレベル（error, warn, info, debug） - デフォルト：info
• MAX_CONCURRENT_REQUESTS：最大同時リクエスト数（1 - 10） - デフォルト：3
• REQUEST_TIMEOUT：リクエストのタイムアウト時間（ミリ秒）（30000 - 600000） - デフォルト：300000

トラブルシューティング

一般的な問題

1. "REPLICATE_API_TOKEN environment variable is required"

   • サーバーは引き続き実行され、この有益なエラーメッセージが表示されます。
   • ReplicateのAPIトークンがMCP設定に正しく設定されていることを確認してください。
   • トークンが有効で、r8_で始まることを確認してください。
   • 注意：APIトークンが欠落している場合でも、サーバーはクラッシュしなくなりました。

2. "Server not showing up in Claude"

   • npx設定を使用している場合は、Node.jsがインストールされていることを確認してください（v18以上）。
   • 手動インストールの場合は、絶対パスが正しいことを確認してください。
   • 設定を変更した後、Claudeデスクトップを再起動してください。
   • JSON設定の構文が有効であることを確認してください。

3. "Generation failed"

   • Replicateアカウントに十分なクレジットがあるか、課金設定が正しいことを確認してください。
   • APIトークンに必要な権限があることを確認してください。
   • 接続をテストするために、より単純なプロンプトで試してみてください。
   • 画像サイズとパラメータが有効であることを確認してください。

4. "npx command not found"

   • Node.jsが正しくインストールされていることを確認してください。
   • node --version と npm --version を実行して、インストールを確認してみてください。

サーバーの安定性向上

✅ 堅牢なエラーハンドリング：APIトークンがなくてもサーバーは引き続き実行されます。 ✅ グレースフルシャットダウン：SIGINTとSIGTERMシグナルを適切に処理します。 ✅ 使いやすいメッセージ：設定手順を含む明確なエラーメッセージを表示します。 ✅ クラッシュの解消：接続が切断される原因となっていた process.exit() 呼び出しを削除しました。 ✅ ローカル画像保存：生成された画像をオフラインでアクセスできるようにローカルにダウンロードします。

デバッグログ

サーバーは標準エラー出力にデバッグ情報を出力し、問題の診断に役立ちます。

• 生成の進行状況の更新
• 有益な指示を含むエラーメッセージ
• API呼び出しの詳細
• グレースフルシャットダウンの通知

パフォーマンスのヒント

• num_inference_steps を下げると、より高速に生成できます（15 - 20を試してみてください）。
• seed パラメータを使用して結果をキャッシュすると、再現性が向上します。
• 使用ケースに適した画像サイズを使用してください。

価格

画像生成の費用は、Replicateの価格体系によって決まります。現在の料金については、Replicate Pricing を確認してください。Hunyuan Imageモデルは、通常、パラメータに応じて1枚あたり約 $0.001 - 0.003 の費用がかかります。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. 適用可能な場合は、テストを追加します。
5. プルリクエストを送信します。

サポート

以下の問題に関しては：

• このMCPサーバー：このリポジトリに問題を報告してください。
• Replicate API：Replicateのサポートに問い合わせてください。
• Hunyuan Imageモデル：Replicateのドキュメントを参照してください。

変更履歴

v2.0.0（最新）

• 🚀 Replicateへの切り替え：安定性と機能を向上させるため、fal.aiからReplicateに移行しました。
• 🔧 依存関係の更新：API統合に replicate パッケージを使用します。
• ⚙️ パラメータの更新：ReplicateのHunyuan Imageモデルに合わせてパラメータを調整しました。
• 📝 ドキュメントの更新：すべてのドキュメントがReplicateの使用を反映するように更新されました。
• 🖼️ WebP形式：画像がより良い圧縮率のWebP形式で保存されるようになりました。

v1.1.0

• 🚀 Hunyuan Imageへの切り替え：画像生成を向上させるため、Qwen ImageからHunyuan Image 2.1に移行しました。
• 🔧 依存関係の更新：fal.ai統合に @fal-ai/client を使用します。
• ⚙️ パラメータの強化：use_reprompt, use_refiner, enable_safety_checker, num_images などの新しいパラメータを追加しました。
• 📝 ドキュメントの更新：すべてのドキュメントがHunyuan Imageの使用を反映するように更新されました。

v1.0.0

• 🎨 Hunyuan Imageの統合：fal.aiを介したHunyuan Imageモデルの完全実装。
• 🔧 接続切断の修正：サーバークラッシュの原因となっていた process.exit() 呼び出しを削除しました。
• 🛡️ エラーハンドリングの改善：APIキーがなくてもサーバーは引き続き実行されます。
• 🌍 ポータビリティの追加：npx設定は任意のマシンで動作します。
• 📦 安定性の強化：グレースフルシャットダウンハンドラーとヌルセーフティチェック。
• 💬 ユーザー体験の向上：設定手順を含む明確なエラーメッセージ。
• 🔄 自動更新：npxがGitHubから自動的に最新バージョンを取得します。
• 📁 ローカル画像保存：生成された画像をローカルディレクトリにダウンロードします。

v0.1.1

• 初期のfal.ai統合
• 基本的な画像生成機能

v0.1.0

• プレースホルダー実装を含む初期リリース

追加リソース

• Replicate上のHunyuan Imageモデル
• Replicate APIドキュメント
• Model Context Protocol仕様
• MCP SDKドキュメント