内容
<!-- 语言：**中文** · [Русский](README.ru.md) -->
**中文** · [Русский](README.ru.md)
# 虚幻 MCP 工具包
[](https://github.com/timargv/UnrealMCPToolkit/releases/latest)
> 通过任意 **MCP 客户端 / 代理** 控制 **虚幻引擎 5.8** 编辑器 — 通用脚本工具（`execute_python`、`execute_console_command`）加上编辑器便利功能（`take_screenshot`、`save_all`、`list_assets`、`get_output_log`）层叠在 Epic 的内置 **模型上下文协议** 服务器上。
[为什么选择此插件？](#为什么选择此插件？) · [需求](#需求) · [安装](#安装) · [快速入门](#快速入门) · [工具](#工具) · [故障排除](#故障排除) · [安全](#安全)
---
## 为什么选择此插件？（与内置 UE MCP 相比）
UE 5.8 附带 Epic 的 **模型上下文协议** 插件 — 但这只是一个 *服务器框架*。开箱即用，它公开了一组单一的“技能”工具集，**无法创建资产、放置演员、运行 PCG 或脚本编辑器**。要使其真正发挥作用，您必须自己编写 C++ 工具。
**虚幻 MCP 工具包就是这项工作 — 完成一次，通用。** 与其编写数十个狭隘的工具，它添加了两个涵盖一切的工具，加上一些安全的编辑器便利功能：
| 工具 | 功能 |
|------|-----------|
| `execute_python` | **整个 `unreal` Python API** — 创建/修改任意资产、PCG 图形、演员、构建、保存、自动化。 |
| `execute_console_command` | **任意** 编辑器/引擎控制台命令（cvars、`stat`、exec 命令）。 |
| `take_screenshot` | **上下文安全** 的活动视口捕获（默认返回文件路径，从不返回巨大的 base64 块）。 |
| `save_all` · `list_assets` · `get_output_log` | 每天的编辑器便利功能，无需每次都编写 Python。 |
**与 Python 远程执行**（VS Code / Rider 方法）相比：相同的功能，但作为 **原生 MCP 工具** 通过一个 MCP 端点公开 — 无需单独的 UDP/TCP 客户端，无需额外的“启用远程执行”设置，结构化请求/响应。
> 它不为您解决特定问题 — 它将编辑器的钥匙交给任何 MCP 客户端。
## 兼容性
| 虚幻引擎 | 状态 |
|---------------|--------|
| 5.8 | ✅ 支持 |
## 需求
- **虚幻引擎 5.8**（启动器或源代码构建）。
- Epic 的 **模型上下文协议** 插件 — 实验性，默认关闭（*编辑 → 插件 → 模型上下文协议*）。
- **Python 编辑器脚本插件** — `execute_python` 所需。
- **MCP 服务器正在运行**：*项目设置 → 插件 → 模型上下文协议 → 自动启动服务器*，或控制台命令 `ModelContextProtocol.StartServer`。默认端点：`http://127.0.0.1:8000/mcp`。
两个引擎插件都声明为 `.uplugin` 中的依赖项，因此使用此插件时会自动启用。
## 安装
### 选项 A — 预编译构建（无需编译）
下载最新的 **[预编译版本](https://github.com/timargv/UnrealMCPToolkit/releases/latest)**（UE 5.8 / Win64），将 `UnrealMCPToolkit` 文件夹提取到项目的 `Plugins/` 目录中，然后启动编辑器 — 无需构建步骤。即使在仅蓝图项目中也有效。您的引擎必须 **完全是 UE 5.8**（预编译二进制文件是版本锁定的）。
### 选项 B — 从源代码
克隆到项目的 `Plugins/` 文件夹中，然后重建：
```bash
git clone https://github.com/timargv/UnrealMCPToolkit.git YourProject/Plugins/UnrealMCPToolkit
```
或添加为子模块：
```bash
git submodule add https://github.com/timargv/UnrealMCPToolkit.git Plugins/UnrealMCPToolkit
```
然后：重新生成项目文件 → 构建编辑器目标 → 启动 → 确认 **虚幻 MCP 工具包** 在 *编辑 → 插件* 中已启用。工具在编辑器启动时注册（并在 `ModelContextProtocol.RefreshTools` 时重新注册）。
## 快速入门
1. 在编辑器中启动 MCP 服务器（参见 [需求](#需求)）。
2. 将您的 MCP 客户端指向服务器端点。示例项目范围配置（格式取决于您的客户端；这是常见的 `.mcp.json` 形状）：
```json
{
"mcpServers": {
"unreal": { "type": "http", "url": "http://127.0.0.1:8000/mcp" }
}
}
```
3. 调用工具。第一个烟雾测试：
```jsonc
// 工具：execute_python
{ "python": "import unreal; unreal.log('hello from MCP'); print(unreal.SystemLibrary.get_engine_version())" }
```
## 工具
### `execute_python`
在编辑器中运行任意 Python 脚本（支持多语句）。返回计算结果和捕获的日志输出；Python 异常作为错误结果返回。
| 参数 | 类型 | 必需 | 描述 |
|-----------|--------|----------|--------------------------|
| `python` | 字符串 | 是 | 要执行的 Python 源代码 |
```json
{ "python": "import unreal\nactors = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)\n[actors.spawn_actor_from_class(unreal.StaticMeshActor, unreal.Vector(i*200,0,0)) for i in range(20)]" }
```
> 注意：对于 UE 5.x 中的演员生成/编辑，优先使用 `unreal.get_editor_subsystem(unreal.EditorActorSubsystem)` 而不是已弃用的 `EditorLevelLibrary`。
### `execute_console_command`
运行单个编辑器/引擎控制台命令并捕获其文本输出。
| 参数 | 类型 | 必需 | 描述 |
|-----------|--------|----------|---------------------------|
| `command` | 字符串 | 是 | 要执行的控制台命令 |
```json
{ "command": "stat unit" }
```
### `take_screenshot`
捕获 **活动编辑器视口**，按比例缩小（保留宽高比）并编码为 JPEG/PNG，位于 `<Project>/Saved/Screenshots/MCP/` 下。
**按设计上下文安全。** 默认情况下，它返回一个小的 **文本** 结果 — 绝对文件路径、像素尺寸和文件大小（以 KB 为单位） — 并且 **从不** 发出 base64 块。传递 `"inline": true` 以内嵌图像，但仅当编码文件低于约 256 KB 的上限时才会内嵌；否则，您将获得路径和一个提示，提示您打开文件。这可以防止全分辨率截图淹没模型的上下文窗口。捕获是同步的，因此在结果返回时，文件已在磁盘上完成。
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|-----------|---------|----------|---------|--------------------------------------------------------------------|
| `width` | 整数 | 否 | `1280` | 最大长边宽度（以像素为单位）（保留宽高比，永不向上缩放），限制在 256..3840 之间 |
| `format` | 字符串 | 否 | `"jpg"` | `"jpg"`（较小）或 `"png"`（无损） |
| `inline` | 布尔值 | 否 | `false` | 如果图像低于大小限制，也内嵌图像 |
```json
{ "width": 768, "format": "jpg" }
```
### `save_all`
保存所有脏映射和内容包，无需对话框（文件 > 保存所有）。
_无参数。_
```json
{}
```
### `list_assets`
列出资产注册表中的资产对象路径，可选按类过滤。输出限制为保持结果较小。
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|-----------|--------|----------|----------|-----------------------------------------------------------------------------|
| `path` | 字符串 | 否 | `/Game` | 递归搜索的内容路径 |
| `class` | 字符串 | 否 | _（无）_ | 类过滤器：短名称（`StaticMesh`）或完整路径（`/Script/Engine.StaticMesh`）；包含子类 |
```json
{ "path": "/Game/Meshes", "class": "StaticMesh" }
```
### `get_output_log`
返回最近的编辑器日志行（由启动时安装的进程内环形缓冲区捕获）。
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|-----------|---------|----------|---------|----------------------------------------------|
| `lines` | 整数 | 否 | `100` | 要返回的最近日志行数，限制在 1..2000 之间 |
```json
{ "lines": 200 }
```
## 故障排除
| 症状 | 解决方法 |
|---------|-----|
| MCP 客户端未列出工具 | 确保 MCP **服务器已启动**，客户端指向 `…/mcp`。在编辑器控制台中运行 `ModelContextProtocol.RefreshTools`。 |
| `execute_python` 失败/不可用 | 启用 **Python 编辑器脚本插件** 并重启编辑器。 |
| 客户端无法连接 | 确认端点/端口（默认 `127.0.0.1:8000`）与 *项目设置 → 模型上下文协议* 匹配。 |
| 启用插件后工具丢失 | 重建编辑器目标；确认 **虚幻 MCP 工具包** 在 *编辑 → 插件* 中已启用；重启。 |
## 🔒 安全
**此插件使用完全的编辑器权限执行任意 Python 和控制台命令。** 连接到 MCP 服务器的任何内容都可以读取/修改您的项目并在您的机器上运行代码。
- 仅在 **受信任的本地开发机器** 上使用。
- 它是一种 `Editor` 类型的模块（在发布版本中排除）— 保持它在任何分发的编辑器版本之外。
- 将 MCP 端点视为特权；不要将其暴露给不受信任的网络/客户端。
## 许可证
[MIT](LICENSE) © 2026 Timur Ragimkhanov
