内容
# 虚幻引擎 MCP
[](https://github.com/FFZackFair92/unreal-engine-mcp/actions/workflows/ci.yml)
[](https://www.python.org/)
[](LICENSE)
[意大利语](README.it.md)
一个 <a href="https://modelcontextprotocol.io">MCP</a> 服务器，允许 AI 代理驱动
虚幻引擎 5：创建项目、导入资产、构建关卡和蓝图，
配置复制、编译 C++、运行 Play In Editor 和打包游戏。
**无需编译 C++ 插件。** 它使用两个已经随引擎附带的插件 — *Python 编辑器脚本插件* 和 *远程控制 API* — 并通过本地 HTTP 与编辑器通信。
```
┌─ 本地层 ── 进程 + 公共 HTTP
│ UnrealEditor.exe, UnrealBuildTool, RunUAT, 资源下载
代理 ──标准输入/输出──▶ MCP │
└─ 编辑器层 ── HTTP :30010（远程控制 API）
└─ 执行 Python 命令 → 运行编辑器
```
本地层存在是因为远程控制 API 仅适用于已经运行的
编辑器：创建项目、启动它、编译
和打包都必须在进程级别进行。
- **68 种工具** 和 **5 种资源** — [完整参考](docs/TOOLS.md)
- **212 个测试**，无需安装虚幻引擎
- **[虚幻自动化笔记](docs/UNREAL-NOTES.md)** — API 陷阱，实战总结
---
## 要求
- 虚幻引擎 **5.0 或更新版本**（开发和测试针对 5.8 — 请参见
[版本兼容性](#unreal-version-compatibility)）
- Python 3.10+
- Windows、Linux 或 macOS。开发发生在 Windows 上，这是本地层最常被测试的地方；Linux 和 macOS 路径（`Build.sh`、
`RunUAT.sh`、`pgrep`）已实现并由 CI 覆盖，但测试较少。
编辑器层是平台中立的。
### 虚幻版本兼容性
服务器在每次调用启动时检测正在运行的引擎支持的内容 —
`ue_status` 在 `capabilities` 下报告它 — 并在缺少功能时
用明确的消息失败，而不是使用神秘的 Python 错误：
| 功能 | 支持版本 |
|---|---|
| 演员、关卡、生成/变换、PIE、项目设置、构建和打包、声音提示 | **5.0+** |
| 蓝图创建、组件（`SubobjectDataSubsystem`）、重新父类 | **5.0+** |
| 材质、材质实例、截图、C++ 类生成 | **5.0+** |
| 通过 Interchange 导入 glTF/`.glb` | **5.2+** （早期：启用 *glTF 导入器* 插件；工具会在出现问题时通知您） |
| 蓝图成员变量 + 按变量复制（`ue_add_variable`） | **5.4+** （在此之前没有 Python API — 工具会明确说明） |
| MetaSounds | 启用 *MetaSound* 插件的任意 5.x 版本 |
自定义引擎构建可以正常工作：检测基于实际的 Python API
表面，而不是版本号。
## 安装
```bash
pip install unreal-engine-mcp
```
或者在不安装任何东西的情况下运行它，如果你有 [uv](https://docs.astral.sh/uv/)：
```bash
uvx unreal-engine-mcp
```
或者从源代码开始，修改它：
```bash
git clone https://github.com/FFZackFair92/unreal-engine-mcp.git
cd unreal-engine-mcp
pip install -e .
```
## 将其连接到您的客户端
服务器通过标准输入/输出通道使用标准 MCP，因此 **任何支持 MCP 的客户端都可以使用** —
Claude、Cursor、VS Code、Windsurf、OpenAI Codex、自定义代理。命令
总是相同的；只有配置的位置不同。
### Claude Desktop / Cowork
`设置 ▸ 开发者 ▸ 编辑配置`，然后添加到 `mcpServers`:
```json
{
"mcpServers": {
"unreal-mcp": {
"command": "python",
"args": ["-m", "unreal_mcp.server"],
"env": { "UE_MCP_PORT": "30010" }
}
}
}
```
### Claude 代码
```bash
claude mcp add unreal-mcp -- python -m unreal_mcp.server
```
### 游标
`~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json` 在项目中 — 与 Claude Desktop 相同的 JSON
形状（`mcpServers` 根键）。
### VS Code（Copilot 代理模式）
`.vscode/mcp.json` — 注意根键是 `servers`：
```json
{
"servers": {
"unreal-mcp": { "type": "stdio", "command": "python", "args": ["-m", "unreal_mcp.server"] }
}
}
```
### 风暴
`~/.codeium/windsurf/mcp_config.json` — 与 Claude Desktop 相同的 `mcpServers` 形状。
### OpenAI Codex CLI
`~/.codex/config.toml`:
```toml
[mcp_servers.unreal-mcp]
command = "python"
args = ["-m", "unreal_mcp.server"]
```
### OpenAI 代理 SDK（自定义代理）
```python
from agents.mcp import MCPServerStdio
unreal = MCPServerStdio(params={"command": "python", "args": ["-m", "unreal_mcp.server"]})
```
在编辑配置后完全重启客户端。在每种情况下，`python`
必须是您运行 `pip install -e .` 的解释器 — 如果有疑问，请使用绝对路径。
> **注意：** ChatGPT 的连接器 UI 仅接受 *远程* MCP 服务器。此
> 服务器按设计为标准输入/输出/本地（它驱动您机器上的进程），因此请从
> 客户端使用标准输入/输出支持 — 上面的客户端 — 或使用 MCP 代理
> 如果您真的需要 HTTP。
## 设置虚幻引擎端
### 启动项目 — 零设置，零构建
将 [`StarterProject/`](StarterProject/) 复制到任意位置，然后使用任意 UE 5.0+ 打开
`.uproject`：启用插件、安全配置就绪、网络
服务器自动启动。仅使用蓝图和引擎插件，**无需编译** — 不像其他包含 C++ 插件的启动器。
### 新项目 — 无需手动操作
要求代理运行 `ue_project_create`。它写入带有必要插件启用的 `.uproject`、
远程控制所需的 security 标志和
`init_unreal.py`，在每次编辑器启动时启动网络服务器。
```
ue_engine_list → ue_project_create → ue_editor_open → ue_status
```
### 现有项目 — 两个步骤
1. **启用插件**: `编辑 ▸ 插件` → *Python 编辑器脚本插件*。
按提示重启。
2. **勾选一个方框**: `编辑 ▸ 项目设置` → 搜索 *Python* → 选中
**启用远程执行**。
这就是整个设置。服务器通过引擎自己的
Python 远程执行通道发现编辑器 — 无需配置文件，无需 HTTP 端口。
<details>
<summary>HTTP 路由（远程控制 API），适用于多播无法实现的情况</summary>
原生通道使用本地
机器上的 UDP 多播 ping 查找编辑器。那是容易的方式，但它不能跨子网，
一些企业网络和 VPN 适配器完全吞噬多播。在这些情况下
— 或编辑器在 **另一台机器上** — 改用远程控制 API
，使用 `UE_MCP_TRANSPORT=remotecontrol`。
1. **启用插件**: *Python 编辑器脚本插件* 和 *远程控制
API*。按提示重启。
2. **允许远程 Python.** 创建 `Config/DefaultRemoteControl.ini`:
```ini
[/Script/RemoteControlCommon.RemoteControlSettings]
bAutoStartWebServer=True
bAutoStartWebSocketServer=True
RemoteControlHttpServerPort=30010
bEnableRemotePythonExecution=True
bAllowAnyRemoteFunctionCall=False
+CustomAllowedRemoteFunctionCalls=(ClassPath="/Script/PythonScriptPlugin.PythonScriptLibrary")
bAllowConsoleCommandRemoteExecution=False
```
这些是 **两个独立的门控** — 一个解锁对象，另一个解锁
函数调用 — 它们会因不同的错误而失败。`DefaultEngine.ini` 是
错误的文件：`URemoteControlSettings` 被声明
`UCLASS(config = RemoteControl)`。重启编辑器。
在某些键值对较早的引擎版本中，它们只是被忽略 —
较早的版本根本没有对这些调用进行门控。
服务器只监听 `127.0.0.1`，因此远程 Python 执行无法
从机器外部访问。
服务器连接后可以执行的操作，以及如果您真的需要
从另一台机器访问编辑器，如何安全地打开它，请参见
[SECURITY.md](SECURITY.md)。
`bAllowConsoleCommandRemoteExecution` 保持 **关闭**。它启用
`ExecuteConsoleCommand` *通过 Web API*，此服务器从未调用
— 所需的控制台命令（`LiveCoding.Compile`、
`WebControl.StartServer`、`HighResShot`）从 Python 内部通过
`unreal.SystemLibrary.execute_console_command` 发出，不通过该
门控。旧版本的此项目将其设置为 `True`；现有项目可以
将其更改为 `False` 而不会丢失任何内容。
3. **检查**: 在浏览器中打开 `http://127.0.0.1:30010/remote/info`。返回 JSON
表示您已连接。
</details>
### 使用的传输
`ue_status` 报告它。默认情况下（`UE_MCP_TRANSPORT=auto`），服务器首先尝试
原生通道，然后回落到 HTTP，因此以任一方式设置的项目
都可以使用。设置 `pyremote` 或 `remotecontrol` 以固定一个。
## 它能做什么
| 领域 | 亮点 |
|---|---|
| **项目** | 查找引擎安装、从规范创建项目、管理插件 |
| **编辑器生命周期** | 打开（等待桥梁）、状态、干净关闭 |
| **C++** | 生成可编译的类，附带正确编写的样板，然后将蓝图重新父类到它们 |
| **构建** | 在后台编译 C++；`ue_live_compile` 在编辑器打开时重新编译 **，使用实时编译 |
| **打包** | `RunUAT BuildCookRun` → 独立可执行文件，带有阶段报告 |
| **资产** | 导入 `.glb`/`.gltf`/`.fbx`/`.wav`，列出和搜索内容浏览器 |
| **关卡** | 创建和打开关卡，生成/移动/删除演员，批量生成，设置已放置演员的属性 |
| **材质** | 构建材质图，连接 PBR 纹理，材质实例，分配给演员 |
| **蓝图** | 创建，添加组件，类型变量，复制，类默认值，重新父类，编译 |
| **网络** | 复制标志，多客户端 PIE，项目设置 |
| **音频** | 导入 WAV，MetaSound 源，声音提示 |
| **免费资产** | Poly Haven，ambientCG 和 Kenney 下载（均为 CC0），以及直接 URL |
| **反馈** | `ue_screenshot` 捕获视口，以便代理可以看到它构建的内容 |
[docs/TOOLS.md](docs/TOOLS.md) 中的完整参数列表。
### 绕过蓝图图限制
**蓝图节点图不能从 Python 创作。** `EdGraph.Nodes` 是
受保护的，销钉未暴露，也没有链接 API — 这是引擎的硬限制
，不是此服务器的限制。详细信息在
[docs/UNREAL-NOTES.md](docs/UNREAL-NOTES.md)。
有效的方法：**将逻辑放在 C++ 父类中。** 蓝图保留
为组件和可调整值的容器；行为被继承。
```
ue_cpp_class_create # 编写类，以及整个 C++ 模块（如果
# 项目仅为蓝图）
ue_editor_close
ue_build_start # 轮询 ue_build_status 直到运行=false
ue_editor_open
ue_reparent_blueprint # 蓝图现在继承行为
```
名称与新父类上的 `UPROPERTY` 匹配的蓝图变量
被它吸收，因此在编辑器中设置的值在移动后存活下来。标记为
`BlueprintCallable` 的函数可从图表中调用 — 代理可以构建词汇
然后由设计师手动连接。
材质图与蓝图图不同，**完全可脚本化**：
`ue_create_material` 真的会创建和连接节点。
### 其他限制
- **编译 C++ 需要关闭编辑器**，除非更改仅影响
函数体 — 然后 `ue_live_compile` 在编辑器打开时有效。
- **打包始终需要关闭编辑器**：构建步骤会重写编辑器
内存中持有的 DLL。
- **功能可用性因引擎版本而异** — 请参见
[兼容性表](#unreal-version-compatibility)；`ue_status` 报告
正在运行的引擎支持的内容。
- **Fab/Marketplace 内容** 没有公共 API。这些工具会调用社区客户端
[`legendary`](https://github.com/derrod/legendary)。
## 配置
| 变量 | 默认值 | 目的 |
|---|---|---|
| `UE_MCP_TRANSPORT` | `auto` | `auto`，`pyremote`（原生通道）或 `remotecontrol`（HTTP） |
| `UE_MCP_HOST` / `UE_MCP_PORT` | `127.0.0.1` / `30010` | 远程控制端点 |
| `UE_MCP_TIMEOUT` | `180` | 每次调用的超时时间（秒） |
| `UE_MCP_PROJECT` | — | 驱动多个编辑器时要使用的项目 |
| `UE_MCP_MULTICAST_GROUP` / `_PORT` | `239.0.0.1` / `6766` | 原生通道的发现端点 |
| `UE_MCP_MULTICAST_BIND` | `0.0.0.0` | 发现 ping 发送的接口 — 在多个适配器（VPN、WSL、Hyper-V）隐藏编辑器时设置 |
| `UE_MCP_MULTICAST_TTL` | `0` | 保持发现仅限于本机。提高它会将任意代码执行暴露给网络 |
| `UE_MCP_ENGINE_DIRS` | — | 搜索引擎安装的额外文件夹 |
| `UE_MCP_LIBRARY` | `~/UnrealAssetLibrary` | 下载的资产存放位置 |
| `UE_MCP_MAX_DOWNLOAD` | 4 GiB | 每个文件的下载上限 |
如果引擎位于不寻常的位置，您也可以在 `.uproject` 旁边放置一个 `mcp_engine.txt`
文件，文件中包含其路径，或显式传递 `engine_root`。
## 开发
测试套件 **无需安装虚幻引擎即可运行**：`tests/fake_unreal.py` 替代
`unreal` 模块，`tests/fake_server.py` 模拟远程控制
API，同时 **实际执行** 生成的代码片段 — 因此整个链
工具 → 代码片段 → 工具 → 结果都涵盖了。
```bash
pip install -e ".[dev]"
pytest -q
```
添加工具：在 `src/unreal_mcp/ue_side.py`（编辑器端）中添加可重用的帮助程序，
在 `server.py` 中添加 `@mcp.tool()` 函数，并在 `tests/` 中添加测试。有关值得了解的约定，请参见
[CONTRIBUTING.md](CONTRIBUTING.md)。
`ue_side.py` 安装到正在运行的编辑器中，并通过其源代码的哈希值进行索引，
因此编辑器端更改会在下一次调用后立即生效，无需重启服务器 —
并且每次调用都只是一个导入它的小型代码片段。
对 `server.py` 或 `local.py` 的更改需要客户端重启。
## 故障排除
| 症状 | 原因 |
|---|---|
| `No response from http://127.0.0.1:30010` | 编辑器已关闭，或网络服务器未启动 → 控制台：`WebControl.StartServer` |
| `Object Default__PythonScriptLibrary cannot be accessed remotely` | `DefaultRemoteControl.ini` 中缺少 `bEnableRemotePythonExecution` |
| `Executing function 'ExecutePythonCommandEx' is not allowed` | 缺少 `CustomAllowedRemoteFunctionCalls` 条目 |
| `404 on /remote/object/call` | *远程控制 API* 插件未启用 |
| `NameError: name 'unreal' is not defined` | *Python 编辑器脚本插件* 未启用 |
| `Unable to build while Live Coding is active` | `LiveCodingConsole.exe` 存活时间超过编辑器 — 杀死它（构建工具会自动执行此操作） |
| `No Unreal Engine installation found` | 设置 `UE_MCP_ENGINE_DIRS`，添加 `mcp_engine.txt`，或传递 `engine_root` |
| `ModuleNotFoundError: No module named 'mcp.server.fastmcp'` | 已安装 `mcp` 2.x；此服务器针对 1.x 线。`pip install "mcp<2"` — 重新安装软件包即可 |
## 许可证
MIT — 请参见 [LICENSE](LICENSE)。
## 参考
- [虚幻引擎远程控制](https://dev.epicgames.com/documentation/en-us/unreal-engine/remote-control-for-unreal-engine)
- [远程控制快速入门](https://dev.epicgames.com/documentation/en-us/unreal-engine/remote-control-quick-start-for-unreal-engine)
- [导入 glTF 文件](https://dev.epicgames.com/documentation/en-us/unreal-engine/importing-gltf-files-into-unreal-engine)
- [Poly Haven API](https://github.com/Poly-Haven/Public-API) · [ambientCG API](https://docs.ambientcg.com/api/v2/full_json/)
