ChiR24/Unreal_mcp

# Unreal Engine MCP 服务器 [](https://opensource.org/licenses/MIT) [](https://www.npmjs.com/package/unreal-engine-mcp-server) [](https://github.com/modelcontextprotocol/sdk) [](https://www.unrealengine.com/) [](https://registry.modelcontextprotocol.io/) [](https://github.com/users/ChiR24/projects/3) [](https://github.com/ChiR24/Unreal_mcp/discussions) 一个功能全面的 Model Context Protocol (MCP) server，使 AI 助手能够通过原生 C++ Automation Bridge 插件控制 Unreal Engine。使用 TypeScript 和 C++ 构建。 ## 目录 - [功能](#features) - [快速开始](#getting-started) - [配置](#configuration) - [可用工具](#available-tools) - [Docker](#docker) - [文档](#documentation) - [社区](#community) - [开发](#development) - [贡献](#contributing) ## 功能 | 类别 | 功能 | |----------|-------------| | **资产管理** | 浏览、导入、复制、重命名、删除资产；创建材质 | | **Actor 控制** | 生成、删除、变换、物理、标签、组件 | | **编辑器控制** | PIE 会话、摄像机、视口、截图、书签 | | **关卡管理** | 加载/保存关卡、流式传输、光照 | | **动画与物理** | 动画蓝图、状态机、布娃娃、载具、约束 | | **视觉效果** | Niagara 粒子、GPU 模拟、程序化效果、调试形状 | | **Sequencer** | 影片、时间轴控制、摄像机动画、关键帧 | | **图表编辑** | Blueprint、Niagara、Material 和 Behavior Tree 图表操作 | | **音频** | Sound Cue、音频组件、混音、环境音 | | **系统** | 控制台命令、UBT、测试、日志、项目设置、CVars | ### 架构 - **原生 C++ 自动化** — 所有操作均通过 MCP Automation Bridge 插件路由 - **双重传输** — 原生 HTTP/SSE（无需桥接）或通过 TypeScript 桥接的 WebSocket - **动态类型发现** — 对灯光、调试形状和 Sequencer 轨道进行运行时内省 - **优雅降级** — 即使没有活动的 Unreal 连接，服务器也会启动 - **按需连接** — 使用指数退避重试自动化握手 - **命令安全** — 通过基于模式的验证拦截危险的控制台命令 - **能力令牌认证** — 可选的基于令牌的身份验证，适用于 WS 和 HTTP 传输 - **资产缓存** — 10 秒 TTL 以提升性能 - **指标速率限制** — Prometheus endpoint 上的基于 IP 的速率限制（60 次请求/分钟） - **集中化配置** — 统一的类别别名和类型定义 ## 快速开始 ### 前置条件 - **Unreal Engine** 5.0–5.8（已验证 5.8 预览版） 选择您的传输方式： - **选项 A：原生 MCP**（推荐） — 无需额外依赖 - **选项 B：TypeScript 桥接** — 需要 **Node.js** 18+ ### 步骤 1：安装 MCP Server（仅限选项 B — 原生 MCP 请跳过） **NPX（推荐）：** ``` npx unreal-engine-mcp-server ``` **克隆并构建：** ``` git clone https://github.com/ChiR24/Unreal_mcp.git cd Unreal_mcp npm install npm run build node dist/cli.js ``` ### 步骤 2：安装 Unreal 插件 MCP Automation Bridge 插件位于 `Unreal_mcp/plugins/McpAutomationBridge`。 #### 从源码构建（需要带有代码目标的项目） 您的项目必须具有代码目标（`.sln` 或 `.xcworkspace`）。 仅包含蓝图的项目无法编译原生插件 — 要进行转换，请在编辑器中通过 **Tools > New C++ Class** 添加任意类。 **方法 1：复制文件夹** ``` Copy: Unreal_mcp/plugins/McpAutomationBridge/ To: YourUnrealProject/Plugins/McpAutomationBridge/ ``` **方法 2：外部插件目录（无需复制）** 1. 打开 Unreal Editor → **Edit → Plugins** 2. 点击 **Plugin Directories**（左下角） 3. 在 **Additional Plugin Directories** 中，添加 `Unreal_mcp/plugins/` 的路径 4. 重启编辑器 — 插件将从外部位置加载 这会将路径保存在您的 `.uproject` 文件中，因此无需复制即可保持插件的链接。 当您打开项目时，插件会自动编译 — UE 会检测到 `.uplugin` + `Source/` 并运行 UnrealBuildTool。 **视频指南：** https://github.com/user-attachments/assets/d8b86ebc-4364-48c9-9781-de854bf3ef7d #### 预编译版本（适用于任何项目，包括仅包含蓝图的项目） 构建一次插件，然后分发编译后的二进制文件 — 目标机器上不需要 IDE 或编译。 **1. 构建：** ``` # macOS / Linux ./scripts/package-plugin.sh /path/to/UE_5.6 # Windows scripts\package-plugin.bat C:\Path\To\UE_5.6 ``` 这将生成类似于 `McpAutomationBridge-v0.5.30-UE5.6-Mac.zip` 的压缩包。 **2. 安装：** 解压到 `YourProject/Plugins/` 并打开项目。这样就完成了 — 没有编译步骤。 ### 步骤 3：启用所需的插件 通过 **Edit → Plugins** 启用，然后重启编辑器。

核心插件（必需）

| 插件 | 用途 | |--------|--------------| | **MCP Automation Bridge** | 所有自动化操作 | | **Python Editor Script Plugin** | 基于 Python 的编辑器自动化助手 | | **Editor Scripting Utilities** | 资产/Actor 子系统操作 | | **Niagara** | 视觉效果和粒子系统 | | **Gameplay Abilities** | `manage_gas` 操作 | | **Smart Objects** | AI 智能对象操作 |

可选插件（自动启用）

| 插件 | 用途 | |--------|--------------| | **Level Sequence Editor** | `manage_sequence` 操作 | | **Control Rig** | `animation_physics` 操作 | | **GeometryScripting** | `manage_geometry` 操作 | | **Behavior Tree Editor** | `manage_ai` Behavior Tree 操作 | | **Niagara Editor** | Niagara 创作 | | **Environment Query Editor** | AI/EQS 操作 | | **MetaSound** | `manage_audio` MetaSound 创作 | | **StateTree** | `manage_ai` State Tree 操作 | | **Enhanced Input** | `manage_networking` 输入映射操作 | | **Chaos Cloth** | 布料模拟 | | **Interchange** | 资产导入/导出 | | **Data Validation** | 数据验证 | | **PCG** | 构建启用时的 `manage_pcg` 图表创作与执行 | | **Procedural Mesh Component** | 程序化网格 | | **OnlineSubsystem** | 会话/网络操作 | | **OnlineSubsystemUtils** | 会话/网络操作 |

### 步骤 4：配置 MCP 客户端 #### 选项 A：原生 MCP 传输（直接 HTTP — 无需桥接） 该插件包含一个内置的 MCP Streamable HTTP 服务器。AI 客户端通过 HTTP 直接连接到插件 — 不需要 TypeScript 桥接、Node.js 或 npm。 **在 Unreal 中启用：** 1. **Edit > Project Settings > Plugins > MCP Automation Bridge** 2. 勾选 **Enable Native MCP** 3. 设置端口（默认：`3000`） 4. 可选地设置 **Native MCP Instructions** 以提供项目特定的指导 5. 重启编辑器 **配置您的 MCP 客户端**以在以下地址使用 Streamable HTTP 传输： ``` http://localhost:3000/mcp ``` **Claude Code:** ``` claude mcp add unreal-engine --transport http http://localhost:3000/mcp ``` 或手动在 `~/.claude/settings.json` 或项目 `.mcp.json` 中配置： ``` { "mcpServers": { "unreal-engine": { "type": "url", "url": "http://localhost:3000/mcp" } } } ``` **Cursor** (`.cursor/mcp.json`): ``` { "mcpServers": { "unreal-engine": { "url": "http://localhost:3000/mcp" } } } ``` **验证是否有效：** - **状态栏** — 在编辑器右下角寻找 `● MCP :3000 (2)`。绿点 = 服务器正在运行，括号中的数字 = 活动会话数。点击它可打开设置。 - **输出日志** — 按 `LogMcpNativeTransport` 过滤以查看连接、工具调用和会话活动： LogMcpNativeTransport: Native MCP server started on http://localhost:3000/mcp LogMcpNativeTransport: MCP session initialized: ... (client: claude-code 2.1.92, active sessions: 1) LogMcpNativeTransport: tools/call: inspect (RequestId=...) LogMcpNativeTransport: tools/call completed: ... (tool=inspect, success=true) 功能： - 针对长时间操作的 SSE 流式实时进度传输 - 多个并发会话（同时运行 Cursor + Claude Code 及其他工具） - 动态工具管理 — 默认加载核心工具，通过 `manage_tools` 启用更多 - 通过 `execute_python` 操作执行 Python（内联代码或 .py 文件） - 能力令牌认证 — 在项目设置中启用以提供网络安全性 #### 选项 B：TypeScript 桥接（stdio — 经典设置） 添加到您的 Claude Desktop / Cursor 配置文件中： **使用克隆/构建：** ``` { "mcpServers": { "unreal-engine": { "command": "node", "args": ["path/to/Unreal_mcp/dist/cli.js"], "env": { "UE_PROJECT_PATH": "C:/Path/To/YourProject", "MCP_AUTOMATION_PORT": "8091" } } } } ``` **使用 NPX：** ``` { "mcpServers": { "unreal-engine": { "command": "npx", "args": ["unreal-engine-mcp-server"], "env": { "UE_PROJECT_PATH": "C:/Path/To/YourProject" } } } } ``` ## 配置 ### 环境变量 ``` # 必需 UE_PROJECT_PATH="C:/Path/To/YourProject" # Automation Bridge MCP_AUTOMATION_HOST=127.0.0.1 MCP_AUTOMATION_PORT=8091 # 局域网访问 (可选) # 安全：设置为 true 以允许绑定到非 loopback 地址 (例如 0.0.0.0) # 只有在了解安全影响的情况下才启用。 MCP_AUTOMATION_ALLOW_NON_LOOPBACK=false # 日志 LOG_LEVEL=info # debug | info | warn | error # 可选 MCP_CONNECTION_TIMEOUT_MS=5000 MCP_REQUEST_TIMEOUT_MS=120000 ASSET_LIST_TTL_MS=10000 # 可选的 Prometheus metrics 端点 # 默认为仅限 loopback。非 loopback metrics 需要同时进行显式 opt-in 和提供 token。 # MCP_METRICS_PORT=9100 # MCP_METRICS_HOST=127.0.0.1 # MCP_METRICS_ALLOW_NON_LOOPBACK=false # MCP_METRICS_TOKEN=change-me # 自定义内容挂载点 (逗号分隔) # 具有 CanContainContent 的 Plugins 会注册 /Game/ 之外的挂载点。 # MCP_ADDITIONAL_PATH_PREFIXES=/ProjectObject/,/ProjectAnimation/ ``` ### 局域网访问配置 默认情况下，出于安全考虑，自动化桥接仅绑定到环回地址 (127.0.0.1)。要允许网络中的其他机器访问： **TypeScript (MCP Server)：** ``` MCP_AUTOMATION_ALLOW_NON_LOOPBACK=true MCP_AUTOMATION_HOST=0.0.0.0 ``` **Unreal Engine 插件：** 1. 转到 **Edit → Project Settings → Plugins → MCP Automation Bridge** 2. 在 **Security** 下，启用 **"Allow Non Loopback"** 3. 在 **Connection** 下，将 **"Listen Host"** 设置为 `0.0.0.0` 4. 重启编辑器 ⚠️ **安全警告：** 启用局域网访问会将自动化桥接暴露给您的本地网络。仅在具有适当防火墙规则的可信网络上使用。在使用局域网模式时，**启用能力令牌认证**（在项目设置中设置 `Require Capability Token`）以防止未经授权的访问。 ## 可用工具 在广泛的全工具模式下公开了 **23 个 MCP 工具**。相关操作直接驻留在它们的父工具上，这样客户端加载的上下文更少，同时不会丧失功能。

核心工具

| 工具 | 描述 | |------|-------------| | `manage_asset` | 资产、材质、渲染目标、Behavior Tree | | `manage_blueprint` | Blueprint、SCS 组件、图表编辑、UMG widget、布局、绑定、动画 | | `control_actor` | 生成、删除、变换、物理、标签 | | `control_editor` | PIE、摄像机、视口、截图 | | `manage_level` | 加载/保存、流式传输、光照 | | `system_control` | UBT、测试、日志、项目设置、CVars、Python 执行 | | `inspect` | 对象内省 | | `manage_tools` | 动态工具管理（在运行时启用/禁用） |

世界构建

| 工具 | 描述 | |------|-------------| | `build_environment` | 地形、 foliage、程序化地形、光照、样条线路/河流/栅栏 | | `manage_level_structure` | 关卡、子关卡、世界分区、流式传输、数据层、HLOD、体积 | | `manage_geometry` | 使用 Geometry Script 创建和编辑程序化网格 | | `manage_pcg` | PCG 图表资产、子图表、输入/采样器/过滤器/生成器节点、引脚连接、执行、分区网格大小和节点设置 |

游戏系统

| 工具 | 描述 | |------|-------------| | `animation_physics` | 动画蓝图、骨骼、套接字、物理资产、布料、载具、布娃娃、Control Rig、IK | | `manage_effect` | Niagara、粒子、调试形状、GPU 模拟 | | `manage_gas` | Gameplay Ability System：能力、效果、属性 | | `manage_character` | 角色创建、移动、高级 locomotion | | `manage_combat` | 武器、弹射物、伤害、近战 | | `manage_ai` | AI 控制器、Behavior Tree、EQS、感知、State Tree、Smart Object、Mesh/寻路 | | `manage_inventory` | 物品、装备、战利品表、制作 | | `manage_interaction` | 可交互物、可破坏物、触发器 |

实用程序

| 工具 | 描述 | |------|-------------| | `manage_audio` | 音频资产、组件、Sound Cue、MetaSound、衰减 | | `manage_sequence` | Sequencer、影片、绑定、轨道、回放、关键帧 | | `manage_networking` | 复制、RPC、网络预测、会话、分屏、局域网/语音、游戏框架、输入映射 |

### 支持的资产类型 Blueprint • 材质 • 纹理 • Static Mesh • Skeletal Mesh • 关卡 • 声音 • 粒子 • Niagara 系统 • Behavior Tree ## Docker ``` docker build -t unreal-mcp . docker run -it --rm -e UE_PROJECT_PATH=/project unreal-mcp ``` ## 文档 | 文档 | 描述 | |----------|-------------| | [处理程序映射](docs/handler-mapping.md) | TypeScript 到 C++ 的路由 | | [插件扩展](docs/editor-plugin-extension.md) | C++ 插件架构 | | [测试指南](docs/testing-guide.md) | 如何运行和编写测试 | | [路线图](docs/Roadmap.md) | 开发路线图 | ## 开发 ``` npm run build # Build TypeScript npm run lint # Run ESLint npm run test:unit # Run unit tests npm run test:all # Run all tests ``` ## 社区 | 资源 | 描述 | |----------|-------------| | [项目路线图](https://github.com/users/ChiR24/projects/3) | 追踪路线图进度和优先级 | | [讨论区](https://github.com/ChiR24/Unreal_mcp/discussions) | 提问、分享想法、获取帮助 | | [问题反馈](https://github.com/ChiR24/Unreal_mcp/issues) | 报告 Bug 和请求功能 | ## 贡献 欢迎贡献！请注意： - 提供 Bug 的重现步骤 - 保持 PR 聚焦且精简 - 遵循现有的代码风格 ## 许可证 MIT — 查看 [LICENSE](LICENSE)

标签：AI助手, C++, MITM代理, TypeScript, Unreal Engine, 安全插件, 数据擦除, 模型上下文协议(MCP), 游戏开发, 网络空间测绘, 自动化控制, 自定义请求头, 请求拦截