ue5-gameplay-mcp

这是一个用于操控正在运行的 Unreal Engine 5 游戏的 MCP 服务器。
它接收虚拟手柄、键盘、鼠标的输入，并输出屏幕捕获、日志行和 UMG 状态。

它不是引擎插件，而是客户端。两个插件已经承担了引擎内的处理，并各自持有独立的端口。
本服务器会同时与这两个插件接入，并以统一的工具接口形式提供。

两个插件均为此服务器添加了一小部分 C++ 代码。
它们各自保持独立性，并维持自己的协议。新增部分具有向后兼容性，因此即使是旧客户端也能与重新构建后的游戏进行通信：

• FImageMeta.SourceSize — 游戏的后备缓冲区大小。为将结构体大小保持在 24 字节，它被打包到之前为保留字段的区域中。这使得客户端可以将缩小后的截图上的某个点重新映射回窗口像素。

• CMD_GET_GAME_STATE（520）及 IRemoteGameStateProvider — 详情见下文。

设置

cd ue5_gameplay_mcp
uv sync

需要 MCP Python SDK v2（mcp.server.MCPServer）。

Related MCP server: VERA MCP Server

运行方法

首先启动游戏。
在本项目中，由于 Game 目标在未烹饪（cook）的项目中会立即退出，因此独立游戏是从编辑器的二进制程序运行的：

"C:/Program Files/Epic Games/UE_5.8/Engine/Binaries/Win64/UnrealEditor.exe" "<PATH>/MyProject.uproject" -game -windowed -resx=1280 -resy=720 -log -nosplash

接下来注册服务器。
项目根目录下的 .mcp.json 已经完成了这一步，因此 Claude Code 会自动识别它。
手动执行时的等价命令如下：

claude mcp add ue5-gameplay -- uv run --directory <PATH>/ue5_gameplay_mcp -m ue5_gameplay_mcp

服务器采用延迟连接（lazy connect），因此实际的启动顺序并不重要。
即使它在游戏之前启动，也会在第一次工具调用时建立连接。

可选参数：--host, --console-port, --capture-port, --format, --quality, --max-size, --grid-step, --transport streamable-http --mcp-port 14102。

工具

会话 — game_connect, game_status, game_reset_input

观测（观察） — game_observe, game_state, game_log, game_wait_for_log

动作 — game_pad, game_pad_sequence, game_key, game_mouse, game_console, game_time_scale

UMG — game_ui_dump, game_ui_click, game_ui_focus

API 的设计及缘由

代理的一次往返需要数秒，而游戏却以 60Hz 运行。逐帧操作并不现实，因此设计如下：

• 所有动作工具都接收 duration（持续时间），并会以匹配通信速度的方式在本地执行按下/按住/松开一系列动作。一次往返传达的不是一帧，而是一个意图（intent）。

• 动作工具默认会进行观测。 game_pad(ly=1.0, duration=0.5) 会让角色前进，并返回其结果帧。这只需行动与确认分开执行时一半的往返次数。

• game_pad_sequence 会在输入的时间比输入的确认更重要时，把整个连招（combo）放进一次调用中。

• game_time_scale(0.2) 在需要瞬时精度时，可以赢得游戏内时间。

• hold=True 会在整个回合内持续施加输入，让智能体思考的同时角色也能继续移动。使用 game_reset_input 将其清除。

用数值，而不是像素

game_state 会返回关卡、世界时间、暂停/时间膨胀、玩家 Pawn 的变换、速度、移动模式、摄像机，以及最近 Actor 的距离和规范化屏幕位置。这些正是 game_mouse 接收的 0–1 坐标，因此可以立即瞄准状态报告中发现的目标。此处理的成本仅为图像处理成本的一小部分，并且不会误读 HUD 上的数值。

game_observe(state=True) 将状态并入观测，game_pad(..., state=True) 将状态并入动作，因此移动与确认仍然只需一次往返。

在实际地图中，最近的 Actor 大多是背景物体，因此报告还包含 class_counts（周围扇形范围内所有对象的统计结果）。先读取一次，再用 class_filter="Enemy" 进行过滤。

添加游戏专属数值

内置报告不需要游编写游戏端代码。对于生命值、分数、任务标志器等只有该项目才知晓的信息，可以在任意 Actor 上实现 IRemoteGameStateProvider（Plugins/RemoteConsole2/Source/RemoteConsole2/RemoteGameState.h），并让它返回一个 JSON 对象字符串：

FString AMyGameMode::GetRemoteGameState_Implementation()
{
    return FString::Printf( TEXT("{\"score\":%d,\"wave\":%d}"), Score, Wave );
}

因为它是一个 BlueprintNativeEvent，所以即使在纯 Blueprint 项目中也可以重写。
所有返回值都会以 Actor 名为键存储在 custom 下。

provider 的收集不受距离过滤器影响，因此放置在原点处的计分者（scorekeeper）也会发送报告。非法 JSON 的文本并不会被丢弃，而是会以字符串继续原样透传，因此即便是开机时的简单 Printf 调试也会有作用。

操作菜单的 3 种方法（按推荐顺序）

1. game_ui_dump + game_ui_click — 准确且快速，但只能识别通过 UMG 注册的控件。如果是自定义 Slate UI 的游戏，将不会返回任何内容，但工具会提示这一点，而不是挂起。

2. 手柄导航 — game_pad(buttons=["DOWN"]), game_pad(buttons=["A"])。几乎适用于所有游戏。

3. 观察并点击 — game_observe(grid=True) 会叠加显示带标签的 0–1 坐标网格。从图像中读出目标后，将该数值传给 game_mouse(x=..., y=...)。这种方式不受分辨率限制，也无关 UI 的构建方式。

规范

• 摇杆遵循 UE 的规格：ly=+1 表示前进。（通信协议中水平轴被反转，但这里已经将其校正，因此工具 API 与游戏自身的轴映射语义一致。）

• 鼠标坐标以左上角为原点进行 0–1 标准化，并使用游戏真实的后备缓冲区大小转换为像素。由于捕获有较大的尺寸，所以该大小会单独探测。

• game_observe 仅返回自上次观测以来的新日志行，因此即使在长时间运行的会话中，也不会重新发送相同的输出。

已知问题与未完成部分

• 当游戏由编辑器二进制文件承载时，控制台命令会经由 Python 路由。 FGameAccessAPI::ExecConsoleCommand 会将命令分派给 IConsoleCommandExecutor 的实现 [0]，但如果编辑器的 Python 插件已加载，该位置将是 Python 而非 Cmd。这导致简单的 stat fps 会被反为 SyntaxError。使用时会在首次使用探测一次，若发现这种情况，就会把命令包装进 unreal.SystemLibrary.execute_console_command 中。打包后的构建中没有 Python 执行器，无需使用此顺序；可通过 game_console(via="cmd") 覆盖。

• 屏幕点击需要捕获的截图完全覆盖整个游戏窗口。 在 -game -windowed 模式下这是成立的。如果是带黑边全屏模式，报告源尺寸会包含黑边，导致映射偏移。

• game_state 每次调用都会遍历关卡中的所有 Actor。 对普通地图规模而言说明什么，但在流式加载的开放世界中，应该用空间查询来替代 TActorIterator。

测试

uv run test/smoke_test.py

直接与游戏通信，并写出 smoke_*.<jpg。这样可以肉眼检查查看截图和网格叠加层。

uv run test/mcp_client_test.py

通过标准输入输出（stdio）将服务器作为实际 MCP 客户端启动，涵盖错误路径，运行并测试所有工具。