Hunyuan-mcp-webui

Apple Silicon MacでHunyuan3Dを動かし、画像またはテキストから3Dアセットを生成するためのMCPサーバーとWeb UIです。

Independent community integration. This project is not affiliated with, sponsored by, or endorsed by Tencent. Tencent source code, model weights, trademarks, and generated outputs remain subject to their applicable terms.

できること

• MCP（stdio）からHunyuan3D-2.1の単一画像→3D生成を呼び出す
• Codex native Image Genで単一画像を生成し、そのままHunyuan3D-2.1へ渡す
• Codex native Image Genで正面・左・背面・右の4方向画像を生成し、Hunyuan3D-2mvへ渡す
• Hunyuan3D-Paint-2.1でPBRテクスチャを生成する
• 白基調のWeb UIで入力、進捗、GLBプレビュー、ダウンロードを操作する
• Apple Silicon向けMPS/CPU設定とメモリ節約プロファイルを利用する

生成後のLOD、コライダー、リギングは Hunyuan3D-blender-processor、 ゲーム組み込みは Hunyuan3D-game-integration が担当します。

必要環境

• Apple Silicon Mac（M1以降を推奨）
• macOS
• Python 3.10
• Node.js 20以降（統合Web UIを使う場合）
• 十分な空き容量。モデルweightとキャッシュはGitに含まれません

初回のモデル取得にはHugging Faceへのネットワーク接続が必要です。処理時間と必要メモリはMac、入力、品質設定によって大きく変わります。

セットアップ

git clone https://github.com/KouyamaCreate/Hunyuan-mcp-webui.git
cd Hunyuan-mcp-webui
./setup_macos.sh

従来Web UI:

./run_web_ui.sh
# http://127.0.0.1:8090

3役統合Web UI:

npm --prefix frontend install
./run_frontend.sh
# http://127.0.0.1:4173

UIだけを確認する場合:

HUNYUAN3D_BACKEND=mock ./run_frontend.sh

MCPとして使う

MCPクライアントのstdio commandに次を指定します。

/absolute/path/to/Hunyuan-mcp-webui/run_mcp_server.sh

主要tool、生成モード、Apple Silicon向けprofile、Codex app-server接続の詳細は docs/spec.mdを参照してください。

構成

components/image_worker/    Codex native Image Gen連携
components/shape_worker/    Hunyuan3D-2.1 / Hunyuan3D-2mv shape生成
components/texture_worker/  Hunyuan3D-Paint-2.1 PBR texture生成
frontend/                   統合Web UI
schemas/                    role間のJSON contract
mcp_server.py               MCP stdio server
web_ui.py                   従来Web UI backend

テスト

model weightを使わない軽量テスト:

python3 -m unittest \
  tests.test_pipeline_contracts \
  tests.test_worker_registry \
  tests.test_paint_macos_compat

npm --prefix frontend install
npm --prefix frontend test

tests.test_role_pipelineは、同じ親フォルダにHunyuan3D-blender-processorがある3役構成で実行します。実モデルE2Eは大容量weightと長い実行時間を必要とするため、通常のCIには含めません。

ドキュメント

• docs/spec.md: 現在の実行仕様と操作方法
• docs/multi-project-roadmap.md: 3役プロジェクトの責務と統合計画
• docs/log.md: 実装・互換対応・実機試走の記録
• RIGHTS_AND_LICENSES.md: ファイル群とmodelの権利境界
• CONTRIBUTING.md: 開発・投稿手順
• SECURITY.md: 脆弱性報告

ライセンスと重要な注意

このrepositoryは単一ライセンスではありません。

• 独自のMCP/Web UI統合コード: LICENSE-MCP-WEBUI（MIT）
• Hunyuan3D-2.1由来コード: LICENSE、Notice.txtほか各ディレクトリのnotice
• Hunyuan3D-2mv互換runtime: LICENSE-HUNYUAN3D-2.0とNOTICE-HUNYUAN3D-2.0
• Python/npm依存、model weight、入力画像、生成物: それぞれの配布元・権利者の条件

Tencentのライセンスには地域、用途、配布、表示、acceptable-use等の条件があります。公開repositoryであることは、modelの利用や再配布が無条件に許諾されることを意味しません。利用・配布前にRIGHTS_AND_LICENSES.mdと原文を確認してください。model weight、秘密情報、生成job dataはこのrepositoryに含めません。

Upstream

本プロジェクトはTencent-Hunyuan/Hunyuan3D-2.1を基盤とする独立したintegrationです。研究内容、model card、引用情報は公式upstreamを参照してください。