月別アーカイブ: 2026年8月

UE5 5.8 MCP Server から画面キャプチャを取得できるようにする

UE5 の 5.8 で追加された MCP Server はまだ実験機能扱いで、特に画面キャプチャ系の命令に問題がありました。画像を正しく認識できないだけでなく、使用するとコンテキストウィンドウが溢れてツールが停止してしまいます。

本来画像型として返すべきデータを文字列で返していることが原因です。文字列化した画像データは非常に大きくトークンも消費します。詳しくは先日の記事で解説しています。

そこで、クライアントソフトと UE5 の MCP サーバーとの間に入って、キャプチャデータを認識可能な画像型に変換する MCP サーバーを作ってみました。(Claude が作りました)

ClaudeCode等  -->  UE5 mcp server

間に挟んで以下のようにします

ClaudeCode等  -->  mcp-filter-adapter  -->  UE5 mcp server

これで下の画像のように、Claude Code から画面キャプチャ系の MCP ツールを使って UE5 の Viewport や Editor 全体を認識できるようになります。AI が画面を見ながら操作できるわけです。もちろんこのツールもただの MCP サーバーなので、他のクライアントでも利用できます。

使い方

以下、すでに UE5 の MCP サーバー自体のセットアップは完了しているものとします。セットアップ手順はこちら。

  1. Python 実行用に uv をインストールしておきます
  2. GitHub のリポジトリから git clone します
    • git clone https://github.com/hiroog/mcp-filter-adapter.git
    • 仮に C:\mcp で clone したものとします。フォルダは C:\mcp\mcp-filter-adapter です
  3. クライアントに合わせて mcp.json 等の設定をします
    • 例えば Claude Code の場合は以下のようになります
{
  "mcpServers": {
    "unreal-mcp": {
      "command": "uv",
      "args": [
      	"run",
        "--directory", "C:\\mcp\\mcp-filter-adapter",
        "mcp-filter-adapter",
        "--upstream", "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}
  • 既存の UE5 mcp server の設定を置き換える形で上書きしてください。UE5 の mcp server には必ず mcp-filter-adapter 経由でアクセスするようにします。
  • --directory 後ろのパラメータは mcp-filter-adapter を clone して出来た実際のパスに置き換えてください。
  • --upstream の後ろには UE5 mcp server の URL を指定します。デフォルトのまま利用している場合は書き換える必要ありません。

このあと Claude Code 等のクライアントを完全に終了して立ち上げ直すと、これまでと同じように UE5 の MCP サーバーの Tool が見えているはずです。さらに Tool を使って UE5 の画面のキャプチャを取得することが可能です。

UE5 5.8 MCPサーバーの EditorToolset.EditorAppToolset に含まれる画像系命令は以下のとおりです

Tool名機能
CaptureViewport ビューポートのキャプチャ
CaptureEditorImage エディタ全体のキャプチャ
CaptureAssetImage アセットのサムネイル取得

mcp-filter-adapter がやっていること

UE5 MCP Server のツール呼び出しが返してくる text に、画像と思われるデータが含まれている場合は json をデコードして画像型に変換します。

UE5 MCP Server は画像データの場合でも以下のように json 構造が文字列化されて type=”text” で返ります。

{ "content": [ { "type": "text", "text": "{\"returnValue\":{\"image\":{\"mimeType\":\"image/png\",\"data\":\"iVBORw0KG...\"}}}" } ] }

画像が含まれる場合のみこれを以下のように type = “image” の画像型に変換します。

{ "content": [
  { "type": "image", "mimeType": "image/png", "data": "iVBORw0KG..." },
  { "type": "text",  "text": "{\"returnValue\": {\"image\": \"<image #0>\", \"cameraFOV\": 90, ...}}" } ] }

画像が含まれていない場合は何も変換せずそのまま返します。

リポジトリ

関連ページ

UE5 5.8 MCP が思ったように動かない理由
UE5 5.8 の MCP サーバー機能を使用する

UE5 5.8 MCP が思ったように動かない理由

UE5 は 5.8 から MCP 機能が実験機能として搭載されました。Engine 自体に Plugin として組み込まれているため、外部ツール等をインストールする必要もなく有効化するだけで使えます。ですが実験機能段階ということもあり、なかなか思うように動かないことがあります。今回はそのいくつかの理由を解説します。MCP 機能自体の使い方に関しては以前の解説を参照してください。

日本語の問題

以前の記事でも説明したように、MCP 利用時は UE5 Editor の言語設定を英語に変更しておくことを強くお勧めします。日本語設定のままだと BP ノード名などが部分的に日本語で渡されており AI がだいぶ混乱してしまうようです。以下は Blueprint Editor 上で、PrintString ノードを追加する場合の実際の Tool call の内容を表したものです。(多少簡略化しています)

日本語の場合

  1. ノードを「 Development|PrintString 」で作成しようとしてエラー
  2. ノードを検索して正しい名前を探す
  3. 正しい名前は「デベロップメント|PrintString」だったことが判明
  4. 「デベロップメント|PrintString」でノードを作成して成功

4ターン消費

role: assistant
  content: PrintStringノードをEventGraphに作成し、DoFireBallの`then`ピンに接続、文字列値を\"Fire\"に設定します。
  tool_calls: ue5__call_tool
     tool_name:    create_node
     toolset_name: editor_toolset.toolsets.blueprint.BlueprintTools
     type_id:      Development|PrintString


role: tool
  name: ue5__call_tool
  content: The node could not be created / Development|PrintString does not exist


role: assistant
  tool_calls: ue5__call_tool
     tool_name:      find_node_types
     toolset_name:   editor_toolset.toolsets.blueprint.BlueprintTools
     type_id_filter: PrintString


role: tool
  name: ue5__call_tool
  content: ～


role: assistant
  name: ue5__call_tool
     tool_name:      find_node_types
     toolset_name:   editor_toolset.toolsets.blueprint.BlueprintTools
     type_id_filter: PrintString


role: tool
  name:  ue5__call_tool
  content: {"returnValue":["デベロップメント|PrintString","クラス|PCG出力要素設定|PrintStringを取得","クラス|PCG出力要素設定|SetPrintString"]}


role: assistant
  content: 日本語のtype_idが必要なようです。「デベロップメント|PrintString」でノードを作成します。
  tool_calls: ue5__call_tool
     tool_name:    create_node
     toolset_name: editor_toolset.toolsets.blueprint.BlueprintTools
     type_id:      デベロップメント|PrintString


role: tool
  name: ue5__call_tool
  content: {"returnValue": {"refPath":"/Game/ThirdPerson/Blueprints/BP_ThirdPersonCharacter.BP_ThirdPersonCharacter:EventGraph.K2Node_CallFunction_3"}}

英語の場合

  1. ノードを「 Development|PrintString 」で作成。成功

1ターンで完了

role: assistant
  content: PrintStringノードのtype_idを確認できました。次にPrintStringノードを作成し、DoFireBallの後に接続します。
  tool_calls: ue5__call_tool
     tool_name:    create_node
     toolset_name: editor_toolset.toolsets.blueprint.BlueprintTools
     type_id:      Development|PrintString


role: tool
  name: ue5__call_tool
  content: {"returnValue": {"refPath":"/Game/ThirdPerson/Blueprints/BP_ThirdPersonCharacter.BP_ThirdPersonCharacter:EventGraph.K2Node_CallFunction_4"}}

なぜ日本語設定なのに最初に「 Development|PrintString 」を使おうとするのかというと、LLM が参照している説明文 (tool の description) には英語のまま「Development|PrintString」と書かれている箇所があるからです。そのため初回の呼び出しに失敗し、何度か試行錯誤して正解を探すような挙動になってしまいます。動作効率も落ちますしその分時間もかかるので、最初に英語に設定しておくことをお勧めします。

スクリーンキャプチャ機能の問題

Editor の状態やビューポートの内容を把握するために、AI がスクリーンキャプチャ機能を自発的に使用する場合があります。最近のモデルは Vision 対応のものが殆どで、blender 用 mcp などでもキャプチャを使ってAI が実際の画面見ながら作業することができます。

ところが UE5 5.8 の MCP の場合はスクリーンキャプチャ命令は完全な地雷で、これが走るとコンテキストウィンドウを完全に使い果たしてツールがエラーで停止します。AI は自分からキャプチャを取りに行くことがあるので、スクリーンショット機能を使わないように最初に指示を追加しておくことをお勧めします。

本来 LLM の API は、content の配列として画像やリソース専用の型を必要とします。書式は使用する LLM の API によって異なりますが、以下は説明のために用意した content 配列の一例です。

"content" : [
   { "type": "text", "text": "～" },
   { "type": "image", "data": "<b64>～", "format": "jpeg" },
   ～
]

ところが Unreal Engine 5 の MCP の場合は、構造化されたデータを返す場合にデコードせずに json の文字列をそのまま text で返してしまいます。

例えば画像を返す場合でも以下のように text として埋め込まれます。

"content" : [
   { "type": "text", "text": "{\"returnValue\":{\"image\":{\"mimeType\":\"image/png\",\"data\":\"<b64>～\"}}}"  },
]

ただのテキストなので、base64 エンコードされた巨大な文字列がそのまま文字トークンとして流し込まれます。キャプチャ画像の base64 文字列は数百 KB から M バイト単位になることもあるので、あっという間に Context Window の Token を使い果たしてしまうわけです。

画像として扱うためには、受け取った文字列を認識できる形に変換する必要があります。

おそらく Claude Code のような既製ツールの場合は、UE5 側の対応を待つか MCP の間に変換用のレイヤーを挟み込む必要があるかと思います。そのため対応が入るまでは、キャプチャツールを呼ばないように指示を追加しておくことをお勧めします。

2026/08/04 追記: 変換用のレイヤーツール作りました。Claude Code 等の既存クライアントでも UE5 MCP からキャプチャ画像を取得できます。「UE5 5.8 MCP Server から画面キャプチャを取得できるようにする」

私は自作の AI Agent Tool (ハーネス) を使用しているため、MCP の受け取り側で画像を変換するようにしてみました。この変換はうまくいき、UE5 でもビューポートのキャプチャを正しく画像として認識できるようになりました。画像なので Token 消費も常識的な範囲に収まるようになり、キャプチャツールが走ってしまったせいで Token を使い果たすこともなくなっています。

if getattr(content[0], 'type', None) == 'text':
    text_data= getattr(src_content[0], 'text', '')
    if len(text_data) >= 80*1024:
        if ('"returnValue"' in text_data) and ('"image"' in text_data) and ('"image/' in text_data):
            ue5_json= json.loads(text_data)
            data= ue5_json.get('returnValue',{}).get('image',{})
            cformat= data.get('mimeType','').replace('image/','')
            return  [ {'type': 'image', 'data': data.get('data'), 'format': cformat} ]

関連ページ

UE5 5.8 の MCP サーバー機能を使用する
UE5 Unreal Python を使った MCP のテスト
1bit LLM Bonsai 27b を使ってみる