unreal-mcp

一个 MCP 服务器，用于从 Claude 驱动正在运行的 Unreal Engine 编辑器。

它使用 Epic 官方的 Python Remote Execution 协议： 通过 239.0.0.1:6766 上的 UDP 多播发现编辑器实例，然后通过 TCP 通道在编辑器内运行 Python。

Claude  ──stdio──▶  unreal-mcp  ──UDP discovery + TCP──▶  Unreal Editor (PythonScriptPlugin)

协议的客户端部分未内置。服务器在运行时于你的引擎安装目录中定位 Epic 的 remote_execution.py，因此它能跨引擎版本持续工作。

要求

• Unreal Engine 5.x（针对 5.6 开发）

• Python 3.10+ 和 uv

Related MCP server: unreal-mcp

设置

1. 在 Unreal 中启用远程执行——这是每个人都会遗漏的步骤

远程执行默认关闭。不启用它，编辑器对发现机制不可见，所有工具都会失败。

1. Edit > Plugins → 启用 Python Editor Script Plugin → 重启。

2. Edit > Project Settings > Plugins > Python → 勾选 Enable Remote Execution。

3. 重启编辑器。

2. 安装

cd unreal-mcp
uv sync

3. 注册到 Claude

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "unreal": {
      "command": "uv",
      "args": ["--directory", "E:\\Maya\\unreal-mcp", "run", "unreal-mcp"]
    }
  }
}

然后启动新对话——会话中途添加的服务器不会被已经运行的聊天拾取。

如果你的引擎位于非标准位置，请设置 UNREAL_ENGINE_ROOT：

"env": { "UNREAL_ENGINE_ROOT": "D:\\Epic\\UE_5.6" }

工具

列表类工具使用 limit / offset 分页，并返回 has_more 以及 next_offset。

结果如何返回

工具主体被包装在一个辅助框架中发送到编辑器，该框架将结果赋值给 result 变量，并以 JSON 格式在哨兵标记之间打印。这样可以防止杂散的 print() 或 Unreal 日志行破坏负载，并将编辑器内的异常转换为结构化错误，而不是埋在 stdout 中的堆栈跟踪。

安全说明

unreal_execute_python 在编辑器的解释器中运行无沙箱代码，具有完整的 unreal 模块访问权限。它可以修改或删除项目内容。请像对待编辑器本身的 Python 控制台一样谨慎使用。

故障排除

"未发现正在运行的 Unreal Editor" ——几乎总是上述的 Enable Remote Execution 设置问题。用 unreal_get_status 确认。

"运行命令时丢失连接……" ——编辑器已关闭或被模态对话框阻塞。关闭对话框后重试；会话会自动重新发现。

打开了多个编辑器 ——第一个被发现的节点胜出。 unreal_get_status 会列出所有节点，以便你区分它们。