Nexus Unreal MCP

本文是 NexusMCP / NexusLink 的通用接入说明，适用于任意 UE 4.26+ 工程，不绑定具体游戏工程。
若某工程已集成插件或有独立启动器，以该工程文档为准；本文只讲：如何安装插件、启用 MCP、通过 NexusDesktop 连接 Cursor / CodeBuddy，以及日常使用注意事项。
当前正式版为 NexusLink 2.2.0。可选 UnLua 插件为 NexusLinkExt 1.0.1。插件与中转须使用兼容的 2.x 版本；Shipping 包编译期剔除 MCP。

⚠️ 安全提示：MCP 身份验证 Token 属于访问凭证。文档、聊天记录和截图中必须打码，禁止暴露完整 Token。

1. 功能简介

NexusLink 将 UE 编辑器中的蓝图、资产、PIE、UMG、材质等上下文通过 MCP 提供给 AI，使 AI 能读取编辑器状态并在授权范围内修改工程内容。

支持搜索资产、读写蓝图 / 材质 / UMG / 行为树，以及 PIE Actor 和 Output Log 等信息
支持调试 PIE 以及 Development / DebugGame 独立 Game 的运行时内容，包括 Actor 属性、动画、行为树 / GAS、Widget、日志和视口
支持调试 editor-hosted -server 及 Development / DebugGame Dedicated Server（DS）的运行时内容，包括日志、Actor、AI 行为树和 GAS 等；DS 无视口和 UMG
GAS / Niagara 等 Capability 按宿主工程已有插件自动探测，NexusLink 不强制依赖这些插件
UnLua 的蓝图绑定和运行时 Lua 在可选插件 NexusLinkExt，不进入核心包
默认使用 SearchMode，只暴露 3 个元工具，具体能力按需发现
exec_command、exec_python 默认禁用。安装 NexusLinkExt 后，eval_runtime_lua、dofile_runtime_lua 同样默认禁用

写操作会真实修改工程资产或运行状态。操作后必须检查版本管理变更，确认无误后再提交。

2. 推荐连接方式

推荐使用独立中转程序 NexusDesktop，无需安装 Cursor / Rider 扩展。

Cursor / CodeBuddy
        │ MCP HTTP :6700
        ▼
NexusDesktop（推荐中转）
        │ WebSocket
        ▼
UE NexusLink（HTTP :45000 / WS :55000）

需要开启两层服务：

UE：启用 MCP 服务器
NexusDesktop：启用中转服务器

任一层关闭都会导致 AI 无法连接。端口冲突时会自动顺延，以界面显示的实际端口为准。

本机只开一个中转。NexusDesktop、NexusRider、NexusVSCode 不要同时启用，否则会重复扫描并连接同一个 UE。

3. 开启步骤

推荐流程：安装 NexusLink → UE 启用 MCP → 安装 NexusDesktop → 启用中转 → 复制 MCP 配置 → 验证连接。

3.1 安装 NexusLink 插件

工程若已接入插件，可跳过本节，直接从 3.2 开始。

从 NexusLink Releases 下载当前最新正式版 nexus-mcp-unreal-*.zip
解压到项目 Plugins/NexusLink（目录内应能看到 NexusLink.uplugin）
打开工程，在 Edit → Plugins → Developer → NexusLink 中启用插件
重启编辑器

启用插件不会启动 MCP。HTTP / WebSocket 默认关闭，下一步再勾选「启用 MCP 服务器」。

插件拆两个模块：NexusLink（Runtime，可进 Development / DebugGame 独立 Game / DS）+ NexusLinkEditor（仅编辑器）。Shipping 编译期整体剔除 MCP。

可选：NexusLinkExt（UnLua）

核心包不含 UnLua。需要蓝图 Lua 绑定或运行时 Lua 时再安装：

从 NexusLinkExt Releases 下载当前最新正式版 nexus-mcp-ext-*.zip（tag nexus-linkext-v*）
解压到项目 Plugins/NexusLinkExt（zip 内顶层目录为 NexusLinkExt/）
在 .uproject 中启用 NexusLinkExt，并确认工程已启用 UnLua
重启编辑器，用 search_capabilities 搜 lua

工程里没有 UnLua 时，这些 Capability 不会注册。hotreload_runtime_lua 需要 UnLua 2.x。eval_runtime_lua、dofile_runtime_lua 默认禁用，访问模式仍在 NexusLink 的危险 Capability 设置里。

3.2 启用 MCP 服务器

编辑器 / PIE

打开 Edit → Editor Preferences → Plugins → NexusLink
在「服务器」分类下勾选 启用 MCP 服务器
确认「运行状态」显示已启动
确认编辑器标题栏右侧显示 MCP / WS 端口（默认 45000 / 55000）

设置保存后即时生效；取消勾选会立即停止服务。

临时查看状态可在控制台执行：

NexusLink.Mcp status

只有编辑器进程（含 PIE）会读取 Editor Preferences。独立 Game、Dedicated Server、-game / -server 子进程不会继承勾选，须按下面方式显式启用。

独立 Game / Dedicated Server

独立进程须在原有启动参数末尾追加：

-EnableNexusMcp

示例：

YourGame.exe -log -EnableNexusMcp
UEEditor.exe YourProject.uproject -server -EnableNexusMcp

保留原有 -log、-server 等参数，不要覆盖整行。

若编辑器 MCP 已占用默认端口，新进程会自动使用后续可用端口
打开 NexusDesktop 的「选择 UE 实例」，选择新出现的 Game / DS 实例；多实例时可按进程、PID 或实际端口区分
Dedicated Server 没有视口，不能使用游戏内调试面板；查看状态使用 NexusLink.Mcp status
Shipping 包中 MCP 已被编译期剔除，追加该参数无效

3.3 下载并安装 NexusDesktop

下载地址：https://github.com/bytepine/NexusDesktop/releases

打开页面后选择当前最新正式版：

Windows：下载 NexusDesktop-windows-amd64-v< 版本 >-setup.exe
macOS：下载 .dmg（仅 Apple Silicon）
不要下载 *-update.zip，该文件用于应用内更新，不是安装包

Windows 默认安装到当前用户目录，无需管理员权限。安装完成后从开始菜单启动，程序会常驻系统托盘。

NexusDesktop 启动后会自动检查更新，之后每 6 小时检查一次；也可在托盘菜单中手动选择「检查更新」。

3.4 启用 NexusDesktop 中转

右键系统托盘中的 NexusDesktop 图标
勾选 启用中转服务器（新安装默认关闭，默认端口 6700）
确认状态行显示当前 UE 工程名，而不是「未连接」
多开编辑器或独立 Game / DS 时，通过「选择 UE 实例」切换目标进程

3.5 复制 MCP 客户端配置

托盘菜单选择 MCP 客户端配置…
传输协议选择 Streamable HTTP
选择 Cursor 或 CodeBuddy
复制自动生成的配置

Cursor 配置示例：

{
  "mcpServers": {
    "nexus-unreal": {
      "url": "http://127.0.0.1:6700/stream",
      "headers": {
        "Authorization": "Bearer <从 NexusDesktop 复制的 Token>"
      }
    }
  }
}

CodeBuddy / Windsurf 配置示例：

"nexus-unreal": {
  "url": "http://127.0.0.1:6700/stream",
  "transportType": "streamable-http",
  "headers": {
    "Authorization": "Bearer <Token>"
  }
}

3.6 粘贴到 AI 客户端

Cursor：粘贴到 %USERPROFILE%\.cursor\mcp.json 的 mcpServers 中
CodeBuddy：粘贴到自定义 MCP 配置中
配置中的 URL 应为 http://127.0.0.1:6700/stream；若 Desktop 端口自动顺延，以托盘显示的实际端口为准

3.7 验证连接

重启 MCP 会话或重新打开 AI 面板
确认 nexus-unreal 显示已连接
SearchMode 下应看到 3 个元工具：search_capabilities、call_capability、submit_feedback
向 AI 输入：「使用 MCP 告诉我当前 UE 编辑器信息。」
确认 AI 返回实际编辑器信息。

4. 日常使用

用户无需记忆具体 Capability 名称，直接描述目标，并明确要求 AI 使用 MCP 即可。

常见用法：

「使用 MCP 查看 BP_xxx 有哪些变量」
「使用 MCP 检查当前 PIE 中玩家角色的位置和可见性」
「使用 MCP 检查当前 DS 中指定 Actor、行为树或 GAS 的运行状态」
「使用 MCP 把这个 Widget 的文本改为 xxx，保存前先告诉我改动内容」
「使用 MCP 查看 Output Log 中最近的 Error」
「使用 MCP 只看我接下来这次操作的 Output Log」
「使用 MCP 检查这个蓝图是否绑定了 Lua」（需已安装 NexusLinkExt）

使用注意事项：

涉及蓝图、资产、PIE、Lua 等内容时，应要求 AI 先调用 MCP，不要猜资产路径
删除、重命名、停止 PIE 等破坏性操作默认会触发 NexusDesktop 确认
可在 NexusDesktop 设置中将写入前确认设为关闭、仅破坏性操作或全部写操作。设为全部写操作时，只对当前 MCP 会话记住
托盘选择「暂停 Agent 转发」后，请求会排队，不会立即发往 UE
写操作完成后检查版本管理变更；不要直接提交未经确认的二进制资产

5. 身份验证与危险 Capability

5.1 MCP 身份验证

2.x 默认开启身份验证。同一台机器上的 UE 与 NexusDesktop 共用本机 Token，通常不需要手工配置；通过 NexusDesktop 复制的 MCP 配置已包含 Bearer Token。

Token 文件：Windows %LOCALAPPDATA%\NexusLink\mcp-auth-token；macOS ~/Library/Application Support/NexusLink/mcp-auth-token；Linux ~/.config/NexusLink/mcp-auth-token
设置面板名称是 MCP 身份验证 / MCP 身份验证 Token
直连 UE :45000 时，必须使用 UE Preferences 中复制的 Token
跨机连接需启用局域网绑定并使用服务端机器的 Token
不要将 MCP 端口映射到公网
不建议关闭身份验证

5.2 危险 Capability

以下能力等价于在进程内执行代码，默认全部禁用。访问模式仍在 Editor Preferences → NexusLink → 危险 Capability；NexusLinkExt 注册的危险能力也会出现在这棵树里。

NexusLink 核心：

exec_command
exec_python

NexusLinkExt（UnLua，安装后才有）：

eval_runtime_lua
dofile_runtime_lua

查某个 unreal.* API 在当前引擎版本是否存在时，用默认开启的只读 get_python_api，不必为此打开 exec_python。

访问模式：

全部禁用：默认。勾选记录保留，但不可调用
每次手动确认：调用须带 reason（至少 24 个字符，说明目的、预期效果，以及为什么没有更安全的专用能力）。编辑器弹窗只允许本次；拒绝或超时（默认 90 秒）后 AI 不应重试。全屏 PIE 看不到窗口时，先退出沉浸模式。独立 Game、Dedicated Server、commandlet 没有确认窗，会直接拒绝
自定义开启：勾选的能力始终允许，不再弹窗

没有确认窗时要启用某一条，用游戏内调试面板的会话勾选（不写配置，退出进程后失效）、「自定义开启」，或启动参数 -NexusEnableDangerousCaps。

只有确认不存在专用 Capability 时才开启，用完建议恢复禁用。

6. 高级用法（按需）

PIE / Development 独立包与 DS

PIE 或 Development / DebugGame 独立 Game 中，可通过控制台打开 MCP 调试面板：

NexusLink.Mcp panel

面板可查看运行状态并临时启停 Capability。临时设置不写入配置，退出进程后失效。访问模式为「全部禁用」时，仍可用面板临时打开某一条危险能力，不影响其他危险能力。

独立 Game / DS 的启用方式见 3.2。Dedicated Server 无视口，使用 NexusLink.Mcp status。独立包和 DS 上「每次手动确认」没有编辑器弹窗，危险能力会被拒绝；需要时改用面板会话勾选、「自定义开启」或 -NexusEnableDangerousCaps。Shipping 包中 MCP 已被编译期剔除。

其他中转方式仅在有明确需求时使用：

NexusVSCode：Cursor / VSCode 内代理，默认 :6900
NexusRider：Rider 代理，默认 :6800
直连 UE：默认 :45000，无代理缓存、写入前确认与暂停能力

不要与 NexusDesktop 同时启用其他中转。

7. 常见问题

MCP 初始化超时 / 无法连接

依次检查：

UE 已勾选 启用 MCP 服务器，或独立 Game / DS 启动参数已包含 -EnableNexusMcp，进程中显示运行中
NexusDesktop 已启动，托盘已勾选 启用中转服务器
NexusDesktop 状态行显示正确的 UE / Game / DS 实例
AI 配置端口与 NexusDesktop 实际端口一致
Bearer Token 来自 NexusDesktop，且没有复制错误

独立 Game / DS 启动后 NexusDesktop 中看不到

确认启动参数包含 -EnableNexusMcp
确认启动日志中出现 NexusLink MCP 启动信息
在 NexusDesktop 中执行「扫描 UE 实例」
多实例时通过「选择 UE 实例」按进程或端口选择

搜不到 Lua / 蓝图绑定相关能力

确认已安装并启用 NexusLinkExt 和 UnLua，然后重启编辑器。这些 cap 不在 NexusLink 核心包里。工程没有 UnLua 时不会注册。eval_runtime_lua 和 dofile_runtime_lua 默认禁用，搜索结果里可能显示为 disabled。

401 / unauthorized

通常是 Token 不匹配，或 NexusDesktop 与 NexusLink 版本不兼容。重新通过 NexusDesktop 复制配置，并确认两端均为兼容的 2.x 版本。

工具调用超时

代理调用超过 120 秒会超时且不重试。避免要求 AI 在整个 /Game/ 下执行无类型限制的宽泛搜索。

修改后磁盘没有变化

部分操作只修改内存，需要执行 save_asset 或在 manage 调用里传 saveToDisk=true。可直接要求 AI：「完成后保存资产并检查结果」。

编辑器正在编译或重启

NexusDesktop 可能返回带 _proxy.degraded 标记的上次只读快照，写操作仍会失败。等待编辑器恢复后再试。

搜不到 GAS / Niagara 等能力

这些 Capability 按宿主工程插件探测。确认工程已启用对应插件并重新编译。独立包只能搜到 Runtime cap，没有编辑器资产 get/manage。

查看 NexusDesktop 日志

托盘菜单选择 打开日志目录。反馈问题时请附上相关时间段日志，并先检查其中是否含需要脱敏的信息。