アンリアル-Blender MCP

Unreal-Blender MCP は、MCP (マシン コントロール プロトコル) アプローチを使用して、AI エージェント経由で Blender と Unreal Engine の両方を制御するための統合サーバーです。

概要

このプロジェクトは、blender-mcpフレームワークを拡張して Unreal Engine のサポートを追加し、Claude や ChatGPT などの AI エージェントが単一のインターフェースを通じて両方のプラットフォームを同時に制御できるようにします。

Related MCP server: soft-ue-cli

サブモジュール情報

このプロジェクトには、Gitサブモジュールとしてblender-mcpが含まれています。リポジトリをクローンする際は、以下のコマンドを使用してください。

# Clone with submodules
git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git

# Or clone normally and then initialize submodules
git clone https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp
git submodule update --init --recursive

特徴

• 統合制御: Blender と Unreal Engine の両方を制御する単一の MCP サーバー

• AIエージェント統合:Claude、ChatGPT、その他のAIアシスタントと連携するように設計されています

• Blender の機能: 以下のすべての Blender-mcp 機能を保持します:

  • シーン操作

  • オブジェクトの作成と編集

  • 資材管理

  • PolyHavenアセット統合

  • Hyper3Dロダンモデル生成

• Unreal Engine の機能:

  • レベルの作成と管理

  • アセットのインポート

  • Pythonコード実行

  • シーン操作

• 拡張構造:アップストリームアップデートとの互換性を維持しながら、Blenderアドオンとサーバーの両方を簡単に拡張できます。

建築

このシステムは、次の 3 つの主要コンポーネントで構成されています。

1. MCP サーバー: ポート 8000 で SSE (Server-Sent Events) を介して AI エージェントと通信する中央ハブ

2. Blender アドオン: ポート 8400 (標準) または 8401 (拡張) 上の Blender 内のソケット サーバー

3. Unreal プラグイン: ポート 8500 上の Unreal Engine 内の HTTP サーバー

[AI Agent] <--SSE--> [MCP Server (8300)] 
                        |
                        |--HTTP--> [Blender Addon (8400)]
                        |
                        |--HTTP--> [Unreal Plugin (8500)]

拡張構造

このプロジェクトでは、アップストリームの変更との互換性を維持するために拡張アプローチを使用しています。

• Blenderアドオン拡張機能：元のコードをそのままに、元のBlenderMCPServerを拡張します

• サーバー拡張機能: 追加ツールと Unreal Engine の統合により元のサーバーを拡張します

• インターフェースツール:拡張機能のインストール、設定、実行のためのユーティリティを提供します

このアプローチにより、コードの競合なしに元のプロジェクトから簡単に更新できます。

ステップバイステップのインストールとセットアップガイド

前提条件

• Python 3.10以降

• Blender 3.0以降

• Unreal Engine 5.0以降

• uv パッケージ マネージャー (ない場合は、 pip install uvでインストールしてください)

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

# Clone with submodules (recommended)
git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp

# Or if you already cloned without --recursive:
git clone https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp
git submodule update --init --recursive

2. Python環境の設定

# Create a virtual environment and activate it
uv venv
# On Windows:
.\venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install project dependencies
uv pip install -e .

3. Blenderアドオンをインストールする

次のいずれかのオプションを選択します。

オプションA: 標準アドオン（オリジナルblender-mcp）

1. ブレンダーを開く

2. 編集 > 設定 > アドオンに移動します

3. 「インストール...」ボタンをクリック

4. blender-mcp/addon.pyファイルを参照して選択します

5. 「インターフェース: Blender MCP」アドオンを有効にする（チェックボックスをオンにする）

オプションB: 拡張アドオン（追加機能付き）

1. 拡張機能インストーラー スクリプトを実行します。

   python -c "from src.unreal_blender_mcp.blender_addon import BlenderAddonManager; BlenderAddonManager().install_to_blender(force=True)"

2. ブレンダーを開く

3. 編集 > 設定 > アドオンに移動します

4. 「インターフェース: 拡張Blender MCP」アドオンを見つけて有効にします（ボックスにチェックを入れます）

4. Unreal Engineプラグインをインストールする

1. このプロジェクトのUEPythonServerフォルダを見つけます

2. フォルダ全体をUnrealプロジェクトのPluginsディレクトリにコピーします。

   • プロジェクトにPluginsディレクトリがない場合は作成してください

3. プロジェクトでUnreal Engineを起動する

4. メニューの「編集」>「プラグイン」に移動します

5. Python Serverプラグインを見つけて有効にする

6. プロンプトが表示されたらUnreal Engineを再起動します

5. MCPサーバーを起動する

次のいずれかのオプションを選択します。

オプションA: 標準サーバー

# Make sure your virtual environment is activated
python main.py

オプションB: 拡張サーバー（より多くの機能）

# Make sure your virtual environment is activated
python run_extended_server.py

# Optional: Customize server options
python run_extended_server.py --host 127.0.0.1 --port 8080 --log-level DEBUG

6. Blenderサーバー接続を有効にする

1. Blenderを起動します（まだ実行されていない場合）

2. 3DビューポートでNを押してサイドバーパネルを開きます

3. 適切なタブを選択します。

   • 「BlenderMCP」（標準アドオンを使用している場合）

   • 「ExtBlenderMCP」（拡張アドオンを使用している場合）

4. 「サーバーを起動」ボタンをクリックします

5. サーバーが正常に起動したことを確認します（コンソール出力を確認します）

7. Unreal Engineの接続を確認する

1. Unreal Engine が動作し、プラグインが有効になっている

2. Pythonサーバーは自動的に起動するはずです

3. 出力ログ（ウィンドウ > 開発者ツール > 出力ログ）でメッセージを確認します。

4. Unrealプラグインはコマンドを受信できる状態になりました

8. AIエージェントを接続する

オプションA: Claude for Desktopとの統合

Claude for Desktop の構成に以下を追加します。

{
    "mcpServers": {
        "unreal-blender": {
            "command": "uvx",
            "args": [
                "unreal-blender-mcp"
            ]
        },
        "unreal-blender-ext": {
            "command": "python",
            "args": [
                "/path/to/unreal-blender-mcp/run_extended_server.py"
            ]
        }
    }
}

/path/to/実際のプロジェクト パスに置き換えます。

オプションB: カーソルと統合する

1. カーソル設定を開く

2. MCPセクションへ移動

3. 次のコマンドを追加します。

   • 標準サーバー: uvx unreal-blender-mcp

   • 拡張サーバー: python /path/to/unreal-blender-mcp/run_extended_server.py``/path/to/実際のプロジェクト パスに置き換えます。

オプションC: 他のAIツールとの統合

MCP サーバーとの統合については AI ツールのドキュメントを参照し、次の点に注意してください。

• MCP サーバー URL: http://localhost:8000 (または指定されている場合はカスタム ポート)

9. システムのテスト

すべてのコンポーネントが実行されたら:

1. AI エージェントを使用して Blender と対話するには、次の操作を実行します。

   • 単純な立方体または球体を作成する

   • オブジェクトのプロパティを変更する

   • マテリアルを作成する

2. AI エージェントを使用して Unreal Engine と対話するには、次の操作を実行します。

   • 新しいレベルを作成する

   • アセットを配置する

   • シーンのプロパティを変更する

3. 両方のプラットフォームが連携するより複雑な操作を試してください

トラブルシューティング

問題が発生した場合:

1. すべてのサーバーが実行中であることを確認します（MCP、Blender、Unreal）

2. ポート設定が一致していることを確認します（デフォルト：MCPの場合は8000、Blenderの場合は8400/8401、Unrealの場合は8500）

3. コンソール出力でエラーメッセージを確認する

4. コンポーネントを正しい順序で再起動します: 最初に MCP サーバー、次に Blender、最後に Unreal Engine

システムの開発と拡張の詳細については、プロジェクト ドキュメントとワークフローディレクトリを参照してください。

比較: 標準 vs 拡張

基本機能が必要な場合は標準サーバーを、高度な機能が必要な場合は拡張サーバーを選択してください。

発達

詳細な開発情報については、プロジェクト ドキュメントとワークフローディレクトリを参照してください。

このプロジェクトを拡張するには:

• 新しいBlenderアドオン機能を追加するには： src/unreal_blender_mcp/blender_addon/extended_addon.pyを変更します。

• 新しいサーバーツールを追加するには: src/unreal_blender_mcp/server_extension/extended_server.pyを変更します。

ライセンス

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

謝辞

• このプロジェクトは、Siddharth Ahuja によるblender-mcpをベースに構築されています。

今後の展開

今後のリリースでは、以下の改善が予定されています。

構造化された Unreal Engine API

現在、Unreal Engineとの通信は主にPythonコードの直接実行に依存しています。今後予定されている機能強化では、Blenderとの統合に類似した構造化APIを実装する予定です。

• 一般的な Unreal Engine 操作用の定義済み関数を作成する

• 適切なエラー処理と検証を実装する

• 実行範囲を制限してセキュリティを向上

• 運用の安定性と予測可能性を向上

• 構造を追加しながら下位互換性を維持する

この機能強化により、両エンジン間でより一貫したエクスペリエンスが実現し、システム全体の信頼性が向上します。この計画されている開発の詳細については、ワークフロードキュメントをご覧ください。