内容
<div align="center">
# 虚幻引擎 MCP 工具包
[](LICENSE)
[](https://www.unrealengine.com)
[](https://www.python.org)
[](#)
[](CONTRIBUTING.md)
**通过模型上下文协议，借助 AI 助手控制虚幻引擎。**
</div>
该项目允许 MCP 客户端（Claude Code、Claude Desktop、Cursor、Windsurf 等）通过自然语言驱动虚幻引擎编辑器：生成和配置演员，构建蓝图，连接事件图节点，编辑数据资产等 — 所有操作都通过一个本地 C++ 插件与 Python MCP 服务器进行 TCP 通信。
它源自更广泛的“虚幻引擎 MCP”理念，许多社区项目都进行了探索，然后在蓝图图形编辑方面取得了显著进展：强制转换、分支、序列化、变量获取/设置、引脚拆分/断开/删除，以及真正的编译错误报告路径，所有这些都可以通过 AI 助手实现，而不是在编辑器中手动连接节点。
## ⚠️ 实验状态
- 可能会发生破坏性更改而无需通知。
- 功能可能不完整或不稳定。
- 不建议用于生产环境。
- 主要在 UE 5.5–5.7、Windows 上进行测试。
## 🌟 您可以使用它做什么
| 类别 | 功能 |
|----------|-------------|
| **演员管理** | 生成/删除演员，设置变换，查询属性，按名称查找演员，列出关卡内容，分配网格。 |
| **蓝图开发** | 创建蓝图类，添加/配置组件，设置物理属性，编译并带有真正的错误/警告报告，生成蓝图演员，复制资产，列出蓝图的完整功能集（包括继承）。 |
| **蓝图节点图** | 添加事件/函数节点，连接引脚，添加类型变量 — 以及[扩展图操作](Docs/Tools/blueprint_graph_extensions.md)：动态强制转换，分支，执行序列，上下文变量获取/设置，引脚拆分/断开/删除，节点删除，字面默认值注入，以及完整的图形节点转储（包括接口图）用于跟踪执行链。 |
| **数据资产** | 读取/写入任意数据资产属性（包括嵌套结构体数组），将 DataTable 行转储为 JSON，将 Widget 蓝图的完整小部件树转储为 JSON。 |
| **UMG** | 创建小部件蓝图，添加按钮/文本块，绑定事件和文本。 |
| **编辑器控制** | 聚焦和定位视口。 |
有关完整的工具参考，请参见 [Docs/Tools](Docs/Tools/README.md)。
## 🧩 组件
- **`UnrealMCP/`** — C++ 编辑器插件。在虚幻编辑器中运行本地 TCP 服务器，接收命令，执行编辑器/引擎 API 操作，并返回结构化 JSON。
- **`Python/`** — MCP 服务器（基于 FastMCP）。将 MCP 客户端桥接到插件的 TCP 套接字（默认为端口 `55557`），并在 `Python/tools/` 下组织工具模块。
- **`Docs/`** — 工具参考和设置说明。
## 🚀 快速入门
### 先决条件
- 虚幻引擎 5.5+
- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- MCP 客户端（Claude Code、Claude Desktop、Cursor、Windsurf 等）
### 1. 安装插件
将 `UnrealMCP/` 复制到您的虚幻引擎项目的 `Plugins/` 文件夹中（如果该文件夹不存在，请创建它），这样您最终会得到 `YourProject/Plugins/UnrealMCP/`。
然后：
1. 右键单击您的 `.uproject` 文件 → **生成 Visual Studio 项目文件**。
2. 打开生成的 `.sln` 文件，选择 **开发编辑器**，然后进行编译。
3. 在虚幻编辑器中打开项目。如果出现提示，请在编辑 → 插件 → 编辑器下启用 **UnrealMCP** 插件，然后重启编辑器。
> 更改插件的 C++ 代码后？在编辑器打开时使用实时编码（`Ctrl+Alt+F11`）进行快速迭代循环 — 但请注意，实时编码补丁在编辑器重启后不会持续存在，除非进行完整的重建。 如果您刚刚添加的工具在编辑器重启后神秘地报告“未知命令”，请触摸源文件以强制完全重新编译。
### 2. 设置 Python 服务器
```bash
cd Python
uv sync
```
有关直接连接与基于服务器的设置选项，请参见 [Python/README.md](Python/README.md)。
### 3. 配置您的 MCP 客户端
```json
{
"mcpServers": {
"unrealMCP": {
"command": "uv",
"args": [
"--directory",
"absolute/path/to/this/repository/Python",
"run",
"unreal_mcp_server.py"
]
}
}
}
```
示例位于 [`mcp.json`](mcp.json) 中。该文件的位置取决于您的客户端 — 请参见下表。
| MCP 客户端 | 配置文件位置 |
|------------|------------------------------|
| Claude Desktop | `%USERPROFILE%\.config\claude-desktop\mcp.json`（Windows） |
| Cursor | `.cursor/mcp.json`，位于您的项目根目录 |
| Windsurf | `%USERPROFILE%\.config\windsurf\mcp.json`（Windows） |
### 4. 验证
在打开虚幻编辑器（加载插件）和 Python 服务器指向它时，请求您的 MCP 客户端列出当前关卡中的演员或生成一个立方体。如果它可以端到端工作，您就成功了。
## 🤝 贡献
问题和拉取请求非常受欢迎 — 这确实是一个社区工具，而不是我珍视的个人项目。有关如何设置、（轻量级）编码约定以及什么样的错误报告或拉取请求是好的，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。如果您不确定某件事情是否值得拉取请求，请先打开问题并询问。
## 致谢
该项目建立在向 MCP 客户端公开虚幻引擎的总体思路之上，许多社区项目首先进行了探索。它们中没有一个要求具体归属，但如果您正在寻找该领域的其他工具，在 GitHub 上搜索“虚幻引擎 MCP”将找到几个。
## 许可证
[MIT](LICENSE)
