内容
# UnrealMCP
一款自主拥有的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，用于驱动 **虚幻引擎 5.7 编辑器**，以实现 AI 辅助开发和 **确定性电影制作** —— 设计用于由 Claude Code（或任何 MCP 客户端）控制。
它通过 **stdio** 在一侧和虚幻编辑器的内置 **Python 远程执行** 在另一侧进行 MCP 通信，因此它不需要 **编译的 C++ 插件** —— 这使其在引擎构建中保持可移植。
## 为什么
它取代了两服务器设置（一个 C++ 编辑器内 HTTP 插件 + 一个单独的 Python 桥接器）为一个您完全拥有的服务器，并通过构造修复了两个已获得的错误：
- **关卡保存仅写入 `.umap`，而非 `.uasset`。** 重复的 `.uasset` 共享关卡的包名会导致非确定性的旧关卡加载；一个保存工具通过关卡保存 API 路由世界，并拒绝将 `World` 保存为资产。
- **变更确实持久** —— 每次编辑都执行 `Modify(True)` + 使包变脏，并通过实际编辑器路径保存，因此生成的/编辑的演员在重新加载后存活。
并且它添加了一个确定性的 **电影/插图管道**：通过 Sequencer + 电影渲染队列渲染真实的、符合正统的 3D 资产，而不是与生成式 AI 角色漂移作斗争。
## 工具（35）
- **编辑器和关卡：** `get_status`、`get_level_actors`、`run_console_command`、`open_level`、`save_level`（受 `.umap` 保护）、`get_output_log`、`restart_editor`（干净退出 + 重新启动）、`execute_python`（任意编辑器 Python —— 转义舱）。
- **演员：** `spawn_actor`、`set_property`、`move_actor`、`delete_actors`。
- **资产：** `asset_search`、`asset_save`、`asset_edit`（CRUD）、`asset_dependencies`、`asset_referencers`、`asset_import`、`material_instance`。
- **眼睛（抗老化 `SceneCapture2D`，返回图像）：** `eyes_mirror`、`eyes_focus`、`eyes_look`、`eyes_overview`（自上而下的正交地板计划）。
- **相机/景深：** `set_camera`（光圈、焦距、聚焦方法 + 距离）。
- **电影/电影创作（Sequencer）：** `create_sequence`、`animate_actor`、`play_animation`（骨骼）、`add_camera_cut`、`add_audio`、`add_fade`、`set_actor_visibility_track`、`add_shot`（主/子序列）、`sequence_inspect`。
- **渲染（电影渲染队列，异步请求 → 轮询）：** `render_sequence`、`render_status`。
## 架构
```
Claude Code ⇄ （stdio MCP / FastMCP） ⇄ 此桥接器 ⇄ （UE Python 远程执行，多播 239.0.0.1:6766 / TCP 6776） ⇄ 虚幻编辑器
```
桥接器发送在编辑器的游戏线程上运行的短 Python 片段；每个片段都打印一个 `UMCP_RESULT:<json>` 行，桥接器会解析返回。图像（`eyes_*` 和渲染预览）由编辑器写入磁盘，并作为 MCP 图像内容返回。桥接器位于 **编辑器外部**，因此它在编辑器重启时存活并自动重新连接。
## 要求
- Windows + 虚幻引擎 5.7（已测试）、Python 3.11。
- 在您的 UE 项目中：启用 **Python 编辑器脚本插件**，并 **项目设置 → 插件 → Python → 启用远程执行**（默认值：多播 `239.0.0.1:6766`，绑定 `127.0.0.1`）。在首次运行时，允许您的 `python.exe` 通过防火墙。
## 设置
```powershell
# 1) 安装
py -3.11 -m venv .venv
.venv\Scripts\pip install -e .
# 2) 供应商 Epic 的远程执行客户端。
# 它不作为此存储库的一部分重新分发（版权归 Epic Games 所有，保留所有权利）- 从您自己的引擎安装中复制：
Copy-Item "C:\Program Files\Epic Games\UE_5.7\Engine\Plugins\Experimental\PythonScriptPlugin\Content\Python\remote_execution.py" `
"src\unreal_mcp\vendor\remote_execution.py"
```
## 与 Claude Code 一起使用
将 `.mcp.json.example` 复制到 `.mcp.json`（在此存储库中，或在您的 UE 项目中），修复路径，然后运行 `/mcp` 连接：
```json
{
"mcpServers": {
"unrealmcp": {
"command": "C:/Projects/UnrealMCP/.venv/Scripts/python.exe",
"args": ["-m", "unreal_mcp"],
"env": { "UNREAL_PROJECT_DIR": "C:/Path/To/YourUEProject" }
}
}
}
```
在您的项目上启动编辑器，连接 `/mcp`，然后工具就会出现。
## 备注
- `restart_editor` 请求干净的编辑器退出（从不强制终止）并在分离状态下重新启动它。
- 已针对 vanilla UE 5.7 进行测试。计划了一个延迟的 **ARK 生存崛起开发工具包** 层（附加的，相同的架构）。
- 此服务器故意 **没有** 通用的“在 World 上保存资产”的路径 - 世界仅保存为 `.umap`。
