UnrealRemoteMCP

RemoteMCP プラグイン

メモ

このプロジェクトは UnrealMCP の開発に使用します。

UnrealEngine に組み込まれている Python プラグインを基盤として実装されたMCP サーバーです。 このプラグインの目的は、Unreal の開発者が AI を利用して Unreal プロジェクトを開発しやすくすることです。

プラグインの目標

MCP を試すにあたり、主に以下のシナリオを想定しています。

1. AI によるアイデアの参考：たとえば、エラー情報を判断する際に、MCP を通じて AI にコンテキストを提供し、問題をすばやく特定できるようにします。
2. 一括タスク処理：AI を利用して、大量の反復作業を一度に実行します。たとえば、特定の種類の Actor を一括削除したり、特定の種類の設定を変更したりします。
3. 自動化ワークフロー：n8n などの自動タスクツールと連携させることで、プログラミング経験のないチームメンバー（プランナーなど）も自動化ワークフローを定義できます。

クイックスタート

AI の時代が到来しています。このリポジトリをダウンロードしたら、使い方を AI に直接尋ねることができます。AI が最新バージョンに沿った、より実際的な使用方法を案内してくれるはずです。

このプラグインは Unreal Editor 内で MCP サーバー（Streamable HTTP） を起動します。使い方はとても簡単です。

1. プラグインを Unreal Engine のプラグインディレクトリにクローンします。

   git clone <repository-url> <Unreal-Engine-Plugins-Directory>/RemoteMCP
   

2. Python の依存関係をインストールします。まず、ローカルに uv または pip があることを確認してください。uv の使用を推奨します。Python のバージョンが 3.11 であることを確認し、pip を使って以下の package を指定のディレクトリにダウンロードします。

   cd <Repo>/Content/Python
   uv pip install httpx --target ./Lib/site-packages --force-reinstall --upgrade
   uv pip install mcp[cli] --target ./Lib/site-packages --force-reinstall --upgrade
   uv pip install anyio --target ./Lib/site-packages --force-reinstall --upgrade   
   uv pip install pywin32 --target ./Lib/site-packages --force-reinstall --upgrade
   
   

3. エンジンを起動し、Edit->Plugins パネルで RemoteMCP プラグインを有効にします。

4. エンジンを再起動します。

5. Edit -> Editor Preferences -> MCP Setting->Enable を True に設定します（AutoStart も有効にすることをおすすめします）。その後、エンジンを再起動します。

6. コンソールコマンド mcp.start を実行します。AutoStart を有効にしている場合、この手順は不要です。

これで MCP サーバーが正常に起動しているはずです。Edit -> EditorPreferences->MCP Setting で、MCP サーバーが自動起動するかどうかと対応する Port を確認できます。

その後、任意の MCP クライアント（Cherry Studio、Cursor など）を使って MCP サーバーに接続できます。接続時に Streamable HTTP を選択し、URL に http://localhost:<Your Port>/mcp を入力してください。

設定で Port を変更した場合は、Unreal の Console に MCP.Restart と入力して再起動できます。

使用方法（初めてでも使えます）

以下では「まったく経験のない初心者」の視点から、UE 側、Cursor 側、動作確認、トラブルシューティングまで順を追って説明します。

0）準備するもの

• Unreal Editor：エディター内で実行する必要があります（パッケージ化したゲームではありません）。
• プラグイン：RemoteMCP を有効にし、Unreal に標準搭載されている Python Editor Script Plugin（Edit -> Plugins -> Scripting）も有効にします。
• エディターの再起動：プラグインを有効にした後は、必ず一度再起動してください。

1）Unreal でポートを確認する（必ず最初に行ってください）

1. Edit -> Editor Preferences -> MCP Setting を開きます。
2. Port（たとえば 8422）を探し、控えておきます。
3. ポートを変更した場合は、後でクライアントの URL にも変更後のポートを指定します。

ヒント：サービスのデフォルト URL は http://127.0.0.1:<port>/mcp のような形式です（/mcp パスが必須です）。

2）起動／停止／再読み込み（Unreal コンソールで実行）

Unreal の出力ログ（Output Log）でコンソール入力欄を開き、以下のコマンドを実行します。

• 起動：MCP.Start
• 停止：MCP.Stop
• 再起動（推奨）：MCP.Restart
• ツール一覧をホットリロード（Content/Python/tools/* を変更したのにクライアントに更新が表示されない場合に使用）：MCP.Reload
• 状態を確認：MCP.State

3）Cursor で接続する（推奨：初心者に最適）

A）「AI ワークスペース」を準備する（強く推奨）

1. 任意の場所に空のフォルダーを新規作成し（たとえば D:\UnrealAIWorkspace）、Cursor で開きます。
2. このリポジトリにある CLAUDE.md を空のフォルダーのルートディレクトリにコピーします。
3. Cursor の設定で、Tools & MCP -> Rule and Commands にある include CLAUDE.md in Context をオンにします。

B）Cursor の MCP を設定する（プロジェクト単位の設定：最も安定）

先ほどの「AI ワークスペース」のルートディレクトリに .cursor/mcp.json ファイルを作成し、以下の内容を記述します（<port> を UE で確認したポートに置き換えてください）。

{
  "mcpServers": {
    "unreal_mcp": {
        "type": "streamable-http",
        "url": "http://127.0.0.1:<port>/mcp"
    }
  }
}

説明：127.0.0.1 は Unreal がローカルマシンで実行されていることを示します。Unreal が別のマシンで実行されている場合は、そのマシンの LAN 内 IP に置き換え（ファイアウォールでポートを許可してください）。

C）Cursor で有効化して動作を確認する

1. Unreal に戻り、MCP.Restart を一度実行します。
2. Cursor で Settings -> Tools & MCP を開きます（または設定で「MCP」を検索します）。
3. unreal_mcp を見つけて接続／有効化します。
4. 接続に成功すると、ツール一覧（たとえば get_unreal_state、run_python_script）が表示されます。

4）他の MCP クライアント（Cherry Studio／Inspector など）で接続する

• 接続タイプ：Streamable HTTP を選択します。
• URL：http://127.0.0.1:<port>/mcp

5）初心者が必ず行うこと：最も簡単な 2 つのツールで接続を確認する

接続に成功したら、すぐに以下を呼び出すことをおすすめします。

• get_unreal_state：エンジンが動作中であること、ポート設定が正しいこと、現在のレベル／Actor 数を読み取れることを確認します。
• run_python_script：最小限のスクリプトを実行します（出力は result 変数に書き込むことをおすすめします）。

run_python_script の例：

import unreal
result = {
    "level": unreal.EditorLevelLibrary.get_current_level_name(),
    "actor_count": len(unreal.EditorLevelLibrary.get_all_level_actors())
}

6）よくある問題（「接続できない／反応がない」場合の 90％ はここで解決します）

• 接続できない状態が続く：URL に /mcp が含まれているか確認します。例：http://127.0.0.1:8422/mcp
• ポートを変更したのに古いポートのまま：UE で Port を変更した後、MCP.Restart を実行します。
• ツール一覧が更新されない：UE のコンソールで MCP.Reload を実行します（解決しない場合は MCP.Restart を実行）。その後、クライアントで更新／再接続します。
• リモート接続に失敗する：127.0.0.1 を Unreal を実行しているマシンの IP に置き換え、そのポートのファイアウォール受信規則を許可します。

ツールの拡張

現在、このプラグインが提供するツールは少数です。コア機能は AI が Python コードを作成して実現する仕組みです。Unreal の Python 拡張を基盤に開発しているため、新しいツールの追加も簡単です。

ツールを拡張する場合は、Content\Python\tools\common_tools.py を直接編集できます。以下に例を示します。

def register_common_tools(mcp : UnrealMCP):
    @mcp.tool()
    def first_tool():
        return "Hello from first tool!"
  
    @mcp.game_thread_tool()
    def get_actor_count():
        """Get the number of actors in the current Unreal Engine scene."""
        try:
            # 使用 Unreal 的 ActorIterator 获取所有 Actor
            world = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_editor_world()
            if not world:
                unreal.log_error("Failed to get the current world.")
                return 0
            actor_count = sum(1 for _ in unreal.ActorIterator(world))
            unreal.log(f"Number of actors in the scene: {actor_count}")
            return actor_count
        except Exception as e:
            unreal.log_error(f"Failed to get actor count: {str(e)}")
            return 0

プロジェクト構成

RemoteMCP
├── Content
│   ├── EditorUI
│   │   └── MainPanel.uasset
│   └── Python
│       ├── foundation
│       │   ├── global_context.py
│       │   ├── log_handler.py
│       │   ├── mcp_app.py
│       │   └── utility.py
│       ├── tools
│       │   └── common_tools.py
│       ├── env.bat
│       ├── init_mcp.py
│       ├── inspector.bat
│       └── unreal_python_tools.py
├── Resources
│   └── plugin_image.png
├── Source
│   └── RemoteMCP
│       ├── Private
│       │   └── RemoteMCP.cpp
│       └── Public
│           ├── RemoteMCP.h
│           └── Settings.h
├── PromptCase.md
├── README.md
└── RemoteMCP.uplugin

ライセンス

このプロジェクトは MIT ライセンスに基づくオープンソースです。詳しくは LICENSE ファイルを参照してください。