ChiR24-unreal_mcp_server

EngineWire

EngineWire 可将 Claude、Cursor、VS Code 或任何其他 MCP 客户端连接到正在运行的 Unreal Editor，
并通过原生 C++ 编辑器插件让它构建关卡、Blueprint、UI、材质、特效等内容。

_{🧭 一个工具，超过 400 项功能  ·  ⚙️ 原生 C++ 编辑器插件  ·  🌐 HTTP 或 stdio  ·  🔐 默认仅限本地且受令牌保护  ·  🎮 Unreal Engine 5.0 – 5.8}

🌐 enginewire.dev  ·  🛒 Fab  ·  🚀 快速开始  ·  📖 Wiki  ·  📦 发布版本  ·  💬 讨论区

📌 这是哪个版本？ 本 README 介绍的是稳定版 0.6.0：可在 Fab 和发布页面获取的插件，以及 npm 上的 unreal-engine-mcp-server（latest）。上一版本 0.5.30 提供 23 个独立工具，而不是一个工具；若继续使用 0.5.30 插件，就需要固定使用 [email protected]。请参阅从 0.5.x 升级。

目录 · 功能介绍 · 工作原理 · 快速开始 · unreal 工具 · 配置 · 安全性 · 引擎插件 · Docker · 文档 · 开发 · 社区

功能

总计超过 450 项功能，由单个 MCP 工具提供。助手通过搜索普通词语来查找这些功能，因此无需记住它们的名称。完整列表请见生成的操作参考。

_{使用 MCP 构建的平台游戏关卡，展示于 Unreal Editor 5.8 中。右下角是插件状态：MCP :3000 (1)，表示原生服务正在端口 3000 上运行，且有一个客户端已连接。}

工作原理

EngineWire 插件在编辑器内运行，在编辑器的游戏线程上完成所有工作，并自行提供 MCP 服务。客户端可通过以下两种方式之一连接；两种方式都使用同一个工具 unreal：

所有服务都监听 127.0.0.1，并且需要项目的能力令牌，除非你更改该令牌。

快速开始

快速入门页面配有截图，介绍了整个流程。你需要 Unreal Engine 5.0 到 5.8。从 Fab 安装无需其他条件；从源代码构建插件则需要包含 C++ 代码的项目（仅蓝图项目可从 Fab 安装，或使用预编译二进制文件）。

1. 添加插件

从 Fab 安装（无需编译器）。 在 Fab 上获取 EngineWire。在 Epic Games Launcher 中，打开 Unreal Engine › Library › Fab Library，找到 EngineWire，然后为你的引擎版本点击 Install to Engine。打开项目，在 Edit › Plugins 中启用 EngineWire，然后重启编辑器。Fab 版本默认关闭原生服务：在 Edit › Project Settings › Plugins › EngineWire › Native MCP 中开启 Enable Native MCP Server，然后再次重启。Fab 更新需要经过 Epic 审核，因此 Fab 版本可能晚于此处的最新版本。

从发行版安装。 从发行版页面下载最新发行版中的 EngineWire-plugin-<version>.zip，并将其中的 EngineWire 文件夹复制到你的项目中：

MyGame/Plugins/EngineWire/

或者克隆此仓库：复制 plugins/EngineWire/，或在 .uproject 中通过 "AdditionalPluginDirectories": ["C:/Path/To/Unreal_mcp/plugins"] 引用该文件夹。

打开项目，让 Unreal 重新构建插件。插件加载后，状态栏会显示 MCP :3000 (0)：插件在端口 3000 上提供 MCP 服务。如果看到 “Engine modules cannot be compiled at runtime”，请先在 Visual Studio、Rider 或 Xcode 中构建一次项目。更多信息请参阅安装指南。

https://github.com/user-attachments/assets/d8b86ebc-4364-48c9-9781-de854bf3ef7d

node scripts/package-plugin.mjs "C:/Program Files/Epic Games/UE_5.7"

路线 A · 原生 HTTP（无需 Node.js）

1. Enable Native MCP Server 默认已开启（Edit › Project Settings › Plugins › EngineWire，端口为 3000）；Fab 构建版本默认关闭。如果项目中该选项处于关闭状态，则需要将其开启并重启编辑器。

   

2. 读取插件生成的能力令牌：<YourProject>/Saved/MCP/capability-token。请像对待密码一样妥善保管。

3. 将服务添加到客户端，并在 X-MCP-Capability-Token 标头中发送令牌。Claude Code：

   claude mcp add --transport http unreal-engine http://127.0.0.1:3000/mcp --header "X-MCP-Capability-Token: <token>"
   

   或在项目的 .mcp.json（Claude Code）中从环境变量读取令牌：

   {
     "mcpServers": {
       "unreal-engine": {
         "type": "http",
         "url": "http://127.0.0.1:3000/mcp",
         "headers": { "X-MCP-Capability-Token": "${UNREAL_MCP_TOKEN}" }
       }
     }
   }
   

   Cursor（.cursor/mcp.json）使用相同的 url 和 headers，但不包含 type。VS Code、Windsurf 等客户端：请参阅连接客户端。

4. **检查连接：**客户端连接后，状态栏中的计数会增加。

   

路线 B · stdio（Node.js 20.19+）

此程序包是一个位于同一 /mcp 前端的小型 stdio 代理。客户端直接连接 /mcp 时，每当编辑器关闭或崩溃，连接会话都会丢失，必须手动重新连接。通过代理连接时，编辑器关闭期间每次调用都会返回 NOT_CONNECTED；编辑器重新运行后，首次调用即可连接，无需重新连接。代理会保留编辑器最后一次提供的工具列表，因此即使会话在编辑器启动前就已开始，也能获取实际工具。

将以下内容添加到客户端的 MCP 配置中，例如 Claude Desktop 的 claude_desktop_config.json：

{
  "mcpServers": {
    "unreal-engine": {
      "command": "npx",
      "args": ["-y", "unreal-engine-mcp-server"],
      "env": {
        "UE_PROJECT_PATH": "C:/Path/To/YourProject"
      }
    }
  }
}

UE_PROJECT_PATH（项目文件夹或其 .uproject 文件）用于让代理查找能力令牌（MCP_AUTOMATION_CAPABILITY_TOKEN 可覆盖此设置）。UNREAL_MCP_URL 用于将代理指向其他端点（默认为 http://127.0.0.1:3000/mcp）。请搭配 0.6 插件使用；0.5.x 插件提供的是 23 个独立工具，而非 unreal 网关。

3. 试用

保持编辑器打开，让助手执行 “列出当前关卡中的 Actor”、“在原点上方 300 个单位处生成一个点光源”，或 “截取视口截图”。如果无法连接，请参阅故障排除。

unreal 工具

两种路由都只公开一个 MCP 工具 unreal，包含四种操作。系统只会加载模型即将使用的契约，而不是数百个工具架构：

一次典型的交互：

{ "operation": "search", "query": "spawn actor" }

{ "operation": "describe", "tool": "control_actor", "action": "spawn" }

{
  "operation": "execute",
  "tool": "control_actor",
  "action": "spawn",
  "params": { "classPath": "/Script/Engine.PointLight", "actorName": "KeyLight", "location": [0, 0, 300] }
}

• 参数严格校验。 未声明的名称会被拒绝，并返回 UNDECLARED_PARAMETER 以及允许的名称列表；每个错误都包含可执行的 nextCall。
• 删除需要同意。 所有破坏性功能，以及某些有风险的写入操作，只有在提供来自 describe 的 consentGrant，并将其作为顶层 consent 字段传回后才会运行。
• 名称。 调用时指定 tool + action 组合或功能 ID，例如 "capability": "control_actor.spawn"。

包含真实回复的完整参考：使用网关。

从直接工具调用迁移

两种路由上的单一 unreal 工具都是永久设置；无法选择退出，也无法恢复 23 个工具的列表。仍直接调用规范工具名称的客户端（通过 tools/call 使用 name: "manage_asset"、name: "control_actor" 等）会收到有界、可复制粘贴执行的 DIRECT_TOOL_CALL_REMOVED 回执，而不是路由调用。其 nextCall 只推进一级：对于未知名称，提供 { "operation": "search" }；未提供操作时，提供 { "operation": "describe", "tool": "<tool>" }；调用中已指定操作时，提供 { "operation": "execute", "tool": "<tool>", "action": "<action>", "params": { ... } }。通过 unreal 运行该 nextCall，即可完成迁移。参见升级。

协议版本

两种路由都会在 initialize 时协商 MCP 协议版本：2025-11-25（最新版本）、2025-06-18 或 2025-03-26。客户端请求较旧版本时，会收到 2025-11-25 作为响应。原生路由收到不受支持的 MCP-Protocol-Version 标头时，会返回 HTTP 400。两种路由也会按请求提供 MCP 2026-07-28，无需 initialize 或会话，并会用该版本响应 server/discover。详情请见：docs/protocol.md。

大多数配置只需修改一项设置：Route B 需要设置 UE_PROJECT_PATH；Route A 无需设置。所有设置均列在配置页面。

插件设置（项目设置 › 插件 › EngineWire，保存在 Config/DefaultGame.ini 中）：

环境变量（仅用于 Route B，在客户端的 env 块中）：

安全

• 默认仅限本地访问。 两种路由都只监听 127.0.0.1。LAN 访问需要启用 允许非回环地址，且原生服务只有在启用 要求 Capability Token 时才会绑定到非回环地址。
• Capability Token。 每个项目都会生成一个令牌，保存在 <Project>/Saved/MCP/capability-token（输入 Capability Token 的值可覆盖该令牌），并通过恒定时间比较进行校验。删除该文件并重启编辑器即可轮换令牌。
• 破坏性操作需征得同意。 删除操作和其他部分写入操作需要为每次调用授予同意，插件会自行检查。
• 安全防护。 资源路径仅限 /Game、/Engine、/Script、/Temp 和 /Niagara，内容路径也可以位于已连接编辑器报告的挂载点下；服务器视为文件的参数（例如 filePath，以及即使命名的是资源也包括 outputPath）绝不会使用报告的挂载点；会串联命令或退出编辑器的控制台命令会被阻止；自动化无法访问插件自身的设置。

详情请参阅安全。请通过 GitHub 安全公告私下报告漏洞。

引擎插件

该桥接插件声明了对引擎插件的依赖，因此 Unreal 会在启用该桥接插件时一并启用它们。

该插件支持从 5.0 到 5.8 的所有 Unreal Engine 次要版本。如果无法在你的版本上构建，请附上构建日志提交问题。

Docker

该镜像运行 stdio 代理。它必须能够访问编辑器的 127.0.0.1:3000 上的 /mcp，因此请使用主机网络（Linux），并传入令牌，因为容器无法读取你的项目文件夹：

docker build -t unreal-mcp .
docker run -i --rm --network host -e MCP_AUTOMATION_CAPABILITY_TOKEN=<token> unreal-mcp

使用 -i，不要使用 -t：TTY 会破坏 stdout 上的 MCP 流。

文档

开发

npm install
npm run build              # clean + compile TypeScript to dist/
npm run dev                # run from source with ts-node
npm run lint               # ESLint (CI fails on any warning)
npm run type-check         # tsc --noEmit, sources and tests
npm run test:unit          # Vitest unit tests (no Unreal required)
npm run test:params        # strict parameter audit
npm run registry:generate  # capability records -> generated contracts, native shards, action reference
npm run registry:check     # fail if generated artifacts drift
npm run manifest:check     # fail if the gateway manifest drifts
npm run eval:check         # search-ranking corpus
npm run version:check      # all version sources agree
npm test                   # integration suite (needs a live Unreal Editor serving /mcp)

src/tools/catalog/capabilities/records/ 中的能力记录是唯一事实来源；所有 *.generated.* 文件、插件的 MCP/Generated/ 分片和操作参考文档均由它们生成。切勿手动编辑生成的文件。如何添加能力：开发。

CI 按顺序运行：ESLint（npx eslint . --max-warnings=0）、类型检查、单元测试、registry:check、manifest:check、headers:check、严格参数审计（test:params）和 eval:check，然后运行阻断式运行时依赖审计（npm audit --omit=dev --audit-level=moderate）以及仅供参考的全树审计。Node 20.19 / 26 矩阵还会执行 build。仅当配置了 Unreal Engine 根目录时才会打包插件，因为 CI 运行器不包含引擎。发布压缩包不包含 Binaries/、Intermediate/ 和 Saved/。

社区

**贡献：**请保持拉取请求小而专注，并使用 Conventional Commits 标题；报告 Bug 时请附上复现步骤；遵循现有代码风格。请参阅 CONTRIBUTING.md。

许可证

MIT。请参阅 LICENSE。