py-ue5-mcp-server

py-ue5-mcp-server

Claude 用 Unreal Engine 5 MCP サーバー

このリポジトリには、Claude が自然言語を通じて Unreal Engine 5 とやり取りできるようにする、Model Context Protocol（MCP）の Python サーバーが含まれています。Remote Control API を活用することで、Claude との会話を通じて Unreal Engine 内の 3D オブジェクトや Blueprint アクターを直接作成、操作、制御できます。

概要

この MCP サーバーは、Claude の自然言語処理機能と Unreal Engine の強力な 3D 環境との橋渡しをします。ユーザーは Unreal Engine で作成または変更したい内容を説明するだけで、Claude がそのリクエストを解釈し、MCP サーバーを通じて適切な操作を実行します。

主な機能

• 自然言語による制御：Claude との会話形式のテキストを使って、3D オブジェクトを作成、操作できます
• Blueprint アクターとの連携：シンプルなテキストプロンプトを使って、Blueprint アクターの関数にアクセスできます
• シーン管理：テキストによる指示で、シーンを構築、変更、配置できます
• アセットの検出：Claude を通じて Unreal プロジェクト内のアセットを検索し、利用できます
• リアルタイムのフィードバック：Unreal Engine のビューポートで、結果をすぐに視覚的に確認できます

要件

• Python 3.10+
• Remote Control API プラグインを有効にした Unreal Engine 5.x
• Claude Desktop（Windows）
• Unreal Engine の基礎知識

インストール

1. リポジトリをセットアップする

git clone https://github.com/yourusername/ue5-mcp.git
cd ue5-mcp
pip install uv mcp requests

2. Claude Desktop を設定する

1. Claude Desktop を開きます
2. File → Settings → Developer → Edit Config に移動します
3. claude_desktop_config.json に以下を追加し、パスをローカルのリポジトリに合わせて調整します。

{
  "mcpServers": {
    "ue5-mcp": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\ue5-mcp", "run", "ue5_mcp_server.py"],
      "env": {}
    }
  }
}

注：ほかの MCP サーバーを設定している場合、競合を防ぐために無効にする必要がある場合があります。

3. Unreal Engine を準備する

1. Unreal Engine とプロジェクトを開きます
2. Remote Control API プラグインが有効になっていることを確認します。
   • Edit → Plugins → 「Remote Control API」を検索します
   • 有効になっていることを確認し、必要に応じてエディターを再起動します

使い方

はじめに

1. プロジェクトを開いた状態で Unreal Engine を起動します
2. Claude Desktop を起動します（すでに起動している場合は再起動します）
3. Unreal Engine 内のコンテンツの作成や変更について、Claude とのチャットを開始します

プロンプトの例

Claude で使用できるプロンプトの例を以下に示します。

• 「位置 0, 100, 50 に雪だるまを作成して」
• 「シーンに雪だるまの家族を配置して」
• 「中央の雪だるまのスケールを大きくして」
• 「雪だるまを位置 100, 200, 0 に移動して」
• 「雪だるまを 45 度回転させて」
• 「シーン内のすべてのアクターの一覧を取得して」

単位について

このサーバーでは、すべての測定にセンチメートルをデフォルトの単位として使用します。

• 1 Unreal Unit = 1 センチメートル
• 標準的な雪だるまの寸法は約 350cm × 350cm（3.5m × 3.5m）です
• 位置とスケールはすべて、このセンチメートル基準のシステムに基づきます

動作の仕組み

技術的な実装

UE5-MCP サーバーは、以下の主要コンポーネントを使用します。

1. MCP サーバーのフレームワーク

このサーバーは FastMCP を使用して構築されており、Claude と Unreal Engine の間に双方向の通信チャネルを確立します。主なコンポーネントは以下のとおりです。

# Create the MCP server with lifespan support
mcp = FastMCP(
    "Unreal-Engine-MCP",
    description="Unreal Engine integration through the Model Context Protocol (Default unit: CENTIMETERS)",
    lifespan=server_lifespan
)

2. Unreal Engine への接続

このサーバーは、Unreal Engine 内で動作する組み込み HTTP サーバーである Remote Control API を通じて Unreal Engine に接続します。

# Default Unreal Engine Remote Control API settings
UE_HOST = "http://127.0.0.1"  # localhost
UE_PORT = "30010"             # default port
UE_URL = f"{UE_HOST}:{UE_PORT}/remote/object/call"

3. コアツール

このサーバーは、関数デコレーターを通じて Claude に複数のツールを公開します。

@mcp.tool()
async def get_all_scene_actors(ctx: Context) -> str:
    """Get a list of all actors in the current level"""
    # Implementation...

@mcp.tool()
async def spawn_actor(ctx: Context, blueprint_path: str, ...) -> str:
    """Spawn a blueprint actor in the current Unreal Engine level"""
    # Implementation...
    
@mcp.tool()
async def spawn_snowman_family(ctx: Context, ...) -> str:
    """Spawns a family of three snowmen in the current Unreal Engine level"""
    # Implementation...
    
@mcp.tool()
async def modify_actor(ctx: Context, actor_path: str, ...) -> str:
    """Modify an existing actor's properties in the Unreal Engine level"""
    # Implementation...

4. アクターの操作

このサーバーは、Remote Control API の呼び出しを通じて、シーン内のアクターを作成、変更できます。

# Illustrative example of how actor creation works
spawn_payload = {
    "objectPath": "/Script/EditorScriptingUtilities.Default__EditorLevelLibrary",
    "functionName": "SpawnActorFromClass",
    "parameters": {
        "ActorClass": blueprint_path,
        "Location": {"X": location[0], "Y": location[1], "Z": location[2]},
        "Rotation": {"Pitch": rotation[0], "Yaw": rotation[1], "Roll": rotation[2]}
    },
    "generateTransaction": True
}

各操作は Unreal Engine Remote Control API への HTTP リクエストとして実行され、結果は JSON 形式で返されます。

主な機能

1. 雪だるまファミリーの作成

目玉機能の一つは、1つのコマンドで雪だるまファミリーを作成できることです。サーバーは以下を実行します。

• 最初の雪だるまアクターを作成します
• それを複製し、位置、回転、スケールの異なる雪だるまを2体追加します
• ファミリーの形に並べます

これにより、シンプルな自然言語のコマンドで複雑なシーンを作成できることがわかります。

2. Blueprint アクターの複製

サーバーは、ネイティブの Blueprint 関数を使って、シーン内の既存のアクターを複製できます。

async def duplicate_snowman(
    snowman_actor_path: str, 
    location: Tuple[float, float, float], 
    rotation: Tuple[float, float, float], 
    scale: Tuple[float, float, float], 
    name: Optional[str]
) -> Optional[str]:
    """Calls the Duplicate function in a Blueprint actor"""
    # Implementation...

3. アクターの変更

サーバーは、既存のアクターのあらゆるプロパティの変更に対応しています。

• 位置、回転、スケールを変更します
• アクターの名前を変更します
• その他のプロパティを保持したまま、特定のプロパティのみを更新します

トラブルシューティング

接続の問題

• Claude Desktop を起動する前に、Unreal Engine が起動していることを確認してください
• Unreal Engine で Remote Control API プラグインが有効になっていることを確認してください
• ポート 30010（デフォルトポート）での通信がファイアウォールによってブロックされていないことを確認してください
• Claude Desktop のコンソールでエラーメッセージを確認してください

コマンド実行の問題

• 基本的な機能を確認するため、簡単なコマンドから始めてください
• リクエストの構文を確認してください
• Unreal Engine の出力ログでエラーメッセージを確認してください
• 参照しているアクターまたはアセットがプロジェクト内に存在することを確認してください

サーバーログ

サーバーは、問題の診断に役立つ詳細なログを生成します。

2023-11-15 14:32:45,123 - Unreal-MCP-Server - INFO - Unreal Engine MCP server starting up...
2023-11-15 14:32:45,125 - Unreal-MCP-Server - INFO - Default unit system: CENTIMETERS (1 Unreal Unit = 1 cm)
2023-11-15 14:32:45,234 - Unreal-MCP-Server - INFO - Connected to Unreal Engine Remote Control API

開発とカスタマイズ

関数の追加

サーバーに新しい機能を追加するには：

1. 必要な動作を実装する新しいヘルパー関数を作成します
2. @mcp.tool() デコレーターを使って Claude に公開します
3. docstring で関数を明確に説明します

例：

@mcp.tool()
async def your_new_function(ctx: Context, param1: str, param2: int) -> str:
    """
    Description of what your function does
    
    Parameters:
        param1: Description of param1
        param2: Description of param2
        
    Returns:
        JSON string with the result
    """
    # Implementation...

Blueprint との連携のカスタマイズ

既存の関数を変更するか、使用するアクター専用の関数を新たに作成することで、サーバーをカスタム Blueprint アクターに対応させることができます。

謝辞

このプロジェクトは、Claude 向けの類似した MCP 連携、特に runeape-sats による最初の Unreal Engine MCP サーバーを参考にしています。Claude を作成し、このような連携を可能にしてくださった Anthropic チームに感謝します。