AI」カテゴリーアーカイブ

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 機能が実験機能として搭載されました。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} ]

関連ページ

1bit LLM Bonsai 27b を使ってみる

Qwen3.6 27b をベースにした 1bit (or 3値) モデル Bonsai 27b が公開されました。

Qwen3.6 27b は使い勝手の良いモデルですが、Dense なので推論は低速です。快適に使用するためには性能の高い GPU を使い全部 VRAM に乗せる必要がありました。(詳しくはこちら) Q4 でもエージェントのように長いコンテキストを扱う場合は VRAM 32GB の GPU が必要になります。

Bonsai の 1bit or 2bit (3値) では GGUF でおよそ 4GB と 7GB で非常に小さくなります。少ない VRAM でも動作するのでどれくらい動くのか試してみました。

Ternary 版実行までの手順 (Windows + CUDA)

  1. モデルのダウンロード
  2. GitHub の Prism-ML から llama.cpp のブランチ版をダウンロードします
  3. llama-prism-b1-62061f9-bin-win-cuda-12.4-x64.zip を展開してフォルダ名を “llama-prism” にしておきます
    • llama-prism フォルダはダウンロードしたモデルと同じ場所にあるものとします
  4. cudart-llama-bin-win-cuda-12.4-x64.zip を展開して、中の 3つの DLL ファイルを “llama-prism” フォルダの中にコピーします
  5. 以下の内容でバッチファイルを作成してから実行します
llama-prism\llama-server.exe --model Ternary-Bonsai-27B-Q2_0.gguf --ctx-size 8192 --temp 0.7 --top-p 0.95 --top-k 20 --port 8080 -fa on --fit off --no-mmap -ngl 99
  • モデルや llama-server のパスが異なる場合は修正してください。また –ctx-size の 8192 は、VRAM 容量や用途に合わせて調整してください。VRAM 16GB の場合は 122880 (120K) くらいまで増やせました。
  1. ブラウザで「 http://127.0.0.1:8080 」を開きます
    • ブラウザ上の UI でチャットが可能です
    • Reasoning を有効化する場合は入力欄下側の電球アイコン「💡」から変更してください

使ってみる

Ternary 版 (Q2_0) の速度は GeForce RTX 5060Ti 16GB で 40 tps でした。同じ 2bit 最小の Qwen3.6 UD-IQ2_XXS は 8.75GB で 30 tps だったので、Bonsai の方が小さく高速に動いています。

UE5 5.8 の mcp による Blueprint 編集を試してみましたが、残念ながら途中でループが発生してタスクを完了できませんでした。さすがに過度な期待は禁物です。量子化されたモデルを含めて UE5 の mcp 編集の結果をまとめてみました。

ModelsizeRTX5060TiUE5 BP
Ternary-Bonsai 27b Q2_06.67 GB40 tps
Qwen3.6 27b UD_IQ2_XXS8.75 GB30 tps
Qwen3.6 27b Q3_K_M12.6 GB△ (初回は完了、編集で失敗)
Qwen3.6 27b Q4_K_M15.6 GB

関連ページ

Qwen3.6 27b の速度の比較

Qwen3.6 27b は性能が良く、Local LLM で UE5 の Blueprint 編集もできるなど使い勝手の良いモデルです。ただし Dense モデルなので推論速度はあまり速くありません。以下様々な環境での Qwen 3.6 27b の比較です。tps の値が大きい方が高速です。

CPUGPUMTPなしMTPあり
Ryzen 7 7840HS DDR5-5600— (CPUのみ)2.16 tps3.84 tps
Ryzen 7 7840HS DDR5-5600Radeon 780M (8GB)2.39 tps5.28 tps
Ryzen 7 4750G DDR4-3200Radeon 7600 8GB2.78 tps4.12 tps
Ryzen 7 5700X DDR4-3200GeForce RTX 5060Ti 16GB8.70 tps10.24 tps
Ryzen 9 3950X DDR4-3200GeForce RTX 4060Ti 16GB8.76 tps10.75 tps
Core i7-13700 DDR5-5600GeForce RTX 4060Ti 16GB10.39 tps11.26 tps
Mac mini M4 Pro 12CoreApple Silicon 16 Core11.71 tps
Ryzen AI Max+ 395 LPDDR5X-8000Radeon 8060S (96GB)12.96 tps23.11 tps
Ryzen 7 9700X DDR5-5600Radeon AI PRO R9700 32GB33.10 tps55.73 tps
  • llama.cpp b9957, Qwen3.6 27b UD-Q4_K_M, ctx 4096, PC 側はいずれも Performance Mode に設定

コンパクトなので比較的多くの環境で動きますが、Dense モデルなので快適に使用するためにはそれなりの性能が必要となります。また実際の用途では ctx サイズを増やす必要があり、速度はさらに遅くなります。特にエージェントでは入力プロンプトも長くなるため、追加で Prefill による待ち時間も考慮する必要があります。Prefill では演算性能も重要となりさらに条件が厳しくなります。以下は llama.cpp の llama-bench による pp の値です。値が大きい方が高速です。

CPU/GPUpp512tg128
Ryzen 7 7840HS + Radeon 780M (8GB)CPU+GPU57.32 ± 0.062.49 ± 1.02
Ryzen 7 5700X + GeForce RTX5060 Ti 16GBCPU+GPU28.54 ± 0.058.58 ± 0.02
Mac mini M4 Pro 12Core / 16CoreGPU100.07 ± 0.0211.87 ± 0.04
Ryzen AI Max+ 395 128GB (EVO-X2)GPU274.92 ± 2.4113.02 ± 0.01
Radeon AI PRO R9700 32GBGPU806.69 ± 0.8733.36 ± 0.01

Ryzen AI Max+ 395 の場合は Active パラメータが少なく、代わりに RAM 容量を活かせる 122B-A10B の方が向いていると思うのですが、Qwen3.6 でこのサイズが無いのが残念です。

関連ページ

UE5 Unreal Python を使った MCP のテスト

UE5 5.8 には MCP サーバー機能が搭載されましたが、もともと Unreal Engine には python コードをリモート実行する機能も備わっています。こちらでも似たようなことが可能で、5.8 よりも前のバージョンでも動きます。ただしサンドボックス化されていないため、もし AI エージェントから呼び出す場合は注意が必要となります。

Python Remote Execution の有効化

  1. もし有効になっていなかったらプラグインマネージャーから「Python Editor Script Plugin」を有効化して Editor を起動し直します
    • 大抵デフォルトで有効になっています
  2. メニューの “Edit” → “Project Settings…”
  3. 左側のカテゴリから「Python」を選択して、「Python Remote Execution」の中にある ” Enable Remote Execution? ” にチェックを入れます
  4. Editor を一旦閉じて起動し直します

MCP サーバー化スクリプトを作ってみる

python の remote 呼び出しを mcp 化します。ファイル名は “ue5-python-mcp.py” とします。

import os
import sys
import time

from mcp.server.fastmcp import FastMCP

ue5_root= os.environ.get('UE5_ENGINE_ROOT', 'C:/Program Files/Epic Games/UE_5.8')
sys.path.append( os.path.join( ue5_root, 'Engine/Plugins/Experimental/PythonScriptPlugin/Content/Python' ) )
from remote_execution import RemoteExecution

mcp= FastMCP('ue5-python', json_response=True)

#------------------------------------------------------------------------------

logger= None
def print_err( *msg ):
    if True:
        print( *msg, file=sys.stderr )
    else:
        global logger
        if not logger:
            logger= open( 'log.txt', 'w' )
        logger.write( ' '.join([ str(m) for m in msg]) + '\n' )
        logger.flush()


class UEInterface:
    def __init__( self ):
        self.remote_exec= None

    def find_node( self, nodes, machine ):
        for node in nodes:
            if machine == '*':
                return  node.get('node_id')
            pc= node.get('machine')
            if pc == machine:
                return  node.get('node_id')
        print_err( 'Error: UE5 node %s not found' % machine )
        return  None

    def connect( self ):
        if not self.remote_exec:
            self.remote_exec= RemoteExecution()
            self.remote_exec.start()
            time.sleep( 1 )
            hostname= os.environ.get('COMPUTERNAME',os.environ.get('HOST',os.environ.get('HOSTNAME','*')))
            node_id= self.find_node( self.remote_exec.remote_nodes, hostname )
            if node_id:
                self.remote_exec.open_command_connection( node_id )

    def disconnect( self ):
        if self.remote_exec:
            self.remote_exec.stop()
            self.remote_exec= None

    def script_wrapper( self, script ):
        out_str= 'try:\n'
        for line in script.split('\n'):
            out_str+= ' ' + line + '\n'
        out_str+= '\nexcept Exception as e:\n print("Error:",str(e))\n'
        return  out_str

    def exec( self, script ):
        wrapped= self.script_wrapper( script )
        result= self.remote_exec.run_command( wrapped )
        return  result

    def is_valid( self ):
        return  self.remote_exec

ueinterface= None

def get_api():
    global ueinterface
    if not ueinterface:
        ueinterface= UEInterface()
        ueinterface.connect()
    return  ueinterface

#------------------------------------------------------------------------------

@mcp.tool()
def run_ue5python( script:str ) -> str:
    """
    UE5 の remote_execution 機能を使って python script を実行します。
    UE5 の python api を呼び出すことが出来ます。

    Args:
        script     実行するpythonスクリプト
    """
    api= get_api()
    if not api.is_valid():
        return  'Error: Unable to connect to UE5'
    result= api.exec( script )
    success= result.get('success',False)
    output= result.get('output')
    return  str( { 'success': success, 'output': str(output) } )

#------------------------------------------------------------------------------

if __name__=='__main__':
    mcp.run(transport='stdio')

スクリプトをそのまま実行すると、エラー発生時にうまく動かなくなる場合があります。例外が出た場合、Editor のコンソール上では赤文字でエラーメッセージが表示されているのですが、戻り値として LLM には何も返っていないからです。原因がわからないとエラー時に無駄な試行錯誤を繰り返してしまうので、mcp に渡されたスクリプトコードをあらかじめ “try:” ~ “except” で囲んでエラーを返すようにしています。

AI クライアントアプリ側の MCP 設定例

使用するツールにあわせて設定してください。以下は uv を使う場合の mcp.json の設定例です。環境変数 UE5_ENGINE_ROOT にエンジンのパスを設定します。

  "mcpServers": {
    "ue5": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp",
        "ue5-python-mcp.py"
      ],
      "env": {
        "UE5_ENGINE_ROOT": "C:/Program Files/Epic Games/UE_5.8"
      }
    }
  }

または直接 PYTHONPATH に UE5 の remote_execution.py が置いてあるパスを設定しても構いません。

  "mcpServers": {
    "ue5": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp",
        "ue5-python-mcp.py"
      ],
      "env": {
        "PYTHONPATH": "C:/Program Files/Epic Games/UE_5.8/Engine/Plugins/Experimental/PythonScriptPlugin/Content/Python"
      }
    }
  }

uv を使わない場合は “pip3 install mcp” で mcp モジュールをあらかじめ追加しておいてください。

  "mcpServers": {
    "ue5": {
      "command": "python",
      "args": [
        "ue5-python-mcp.py"
      ],
      "env": {
        "UE5_ENGINE_ROOT": "C:/Program Files/Epic Games/UE_5.8"
      }
    }
  }

実行前の注意点

これはあくまで検証用で、サンドボックス化が行われていないので注意してください。このツールを使うと mcp 経由で任意の python コードが実行可能となります。ファイルアクセスやコマンド実行、ネットワークアクセス等が行われる可能性があるため、使用する場合は必ず安全対策を行ってください。以下はその例です。

  • ローカルアカウントを使ったまっさらな PC を用意して、そこで UE5 を起動する
  • 自動承認を行わず、呼び出されるスクリプトが問題ないか毎回確認してから手動承認する

使ってみる

先に UE5 Editor を起動してから、AI 側のクライアントアプリを起動します。例えば Claude Code のような mcp に対応したコーディングツールを使うことができます。Python の unreal モジュールの命令を AI 経由で実行できます。アセットの編集やレベルへの配置などもエージェントに任せることが可能です。

この方法を使うと 5.8 よりも古い UE5 でエージェントを使用することができます。ただ色々と機能制限はあります。UE5 5.8 の標準の MCP サーバーの方ができることが多く機能が豊富なので、やはり本格的に使う場合はそちらを使った方が良いかと思います。

関連ページ