Nexus Unreal MCP

NexusLink(Fab 上的名称为 NexusMCP)把 AI 客户端接到 Unreal Engine。下面以本机工程为例,从安装插件开始,用 NexusDesktop 连接 Cursor、Windsurf、CodeBuddy 或 Codex,最后让 AI 读出正在运行的工程信息。适用于 UE 4.26 及以上版本,包括 UE5。

本文按 2026 年 11 月 21 日的正式版核对。UE 插件为 NexusLink 2.3.7,桌面中转为 NexusDesktop 2.3.3,需要 UnLua 时再装 NexusLinkExt 1.1.2。

分享 MCP 配置、日志或截图前,请遮住完整的身份验证 Token。本文配置示例中的 <Token> 是占位符。


1. 功能简介

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

  • 可按目录和资产类型搜索,读写蓝图、材质、UMG 和行为树,也能读取 PIE 中的 Actor 与 Output Log。蓝图、Widget 或关卡的部分属性支持修改预览和写后校验

  • 在 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,不进入核心包

  • UE 默认使用 SearchMode,提供 3 个元工具。用 SearchCapabilities 按名称或意图搜索,例如 project info 或 selected actor。按精确名称查询时,参数表会列出已声明的数值范围

  • ExecCommand、ExecPython 默认禁用。安装 NexusLinkExt 后,EvalRuntimeLua、DofileRuntimeLua 同样默认禁用

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


2. 推荐连接方式

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

AI 客户端通过 Streamable HTTP 访问 NexusDesktop,默认地址为 http://127.0.0.1:6700/stream。NexusDesktop 负责发现 UE 实例,再通过 WebSocket 转发调用。UE 侧默认使用 HTTP 45000 和 WebSocket 55000。

需要开启两层服务:

  1. UE:启用 MCP 服务器

  2. NexusDesktop:启用中转服务器

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

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


3. 开启步骤

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

工程已集成插件时,可直接前往「3.2 启用 MCP 服务器」。

  1. 从 NexusLink Releases 下载插件包 nexus-mcp-unreal-2.3.7.zip

  2. 把压缩包内的 NexusLink/ 放入项目的 Plugins/,确认路径为 Plugins/NexusLink/NexusLink.uplugin

  3. 打开工程,在 Edit → Plugins → Developer → NexusLink 中启用插件

  4. 重启编辑器

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

插件包含运行时模块 NexusLink 和编辑器模块 NexusLinkEditor。Development / DebugGame 独立 Game 和 DS 只加载运行时模块。Shipping 在编译时剔除 MCP 服务。需要仓库里的 GAS、行为树复测或 Trace 对比脚本时,从同版本 Release 另取源码包中的 tools/。

可选:NexusLinkExt(UnLua)

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

  1. 从 NexusLinkExt Releases 下载 nexus-mcp-ext-1.1.2.zip

  2. 把压缩包内的 NexusLinkExt/ 放入项目的 Plugins/

  3. 在 .uproject 中启用 NexusLinkExt,并确认工程已启用 UnLua

  4. 重启编辑器,用 SearchCapabilities 搜索 lua

未启用 UnLua 时,扩展能力无法注册。HotReloadRuntimeLua 需要 UnLua 2.x。EvalRuntimeLua、DofileRuntimeLua 默认禁用,访问模式仍在 NexusLink 的危险 Capability 设置里。

3.2 启用 MCP 服务器

编辑器 / PIE

  1. 打开 Edit → Editor Preferences → Plugins → NexusLink

  2. 在「服务器」分类下勾选 启用 MCP 服务器

  3. 确认「运行状态」显示已启动

  4. 确认编辑器标题栏右侧显示 MCP / WS 端口(默认 45000 / 55000)

设置即时生效,取消勾选会停止服务。下图中箭头标出了插件设置和服务器开关。文中截图可点开看原图,界面上的旧版本号和工程名仅作示例。

UE 编辑器偏好设置中的 NexusLink 服务器开关
UE 插件设置。箭头标出了开启 MCP 的位置。

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

NexusLink.Mcp status

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

独立 Game / Dedicated Server

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

-EnableNexusMcp

示例:

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

第二行使用 UE5 的 UnrealEditor.exe,UE4 对应 UE4Editor.exe。实际启动时保留工程原有的 -log、-server 等参数。

  • 若编辑器 MCP 已占用默认端口,新进程会自动使用后续可用端口

  • 打开 NexusDesktop 的「选择 UE 实例」,选择新出现的 Game / DS 实例;多实例时可按进程、PID 或实际端口区分

  • Dedicated Server 没有视口,不能使用游戏内调试面板;查看状态使用 NexusLink.Mcp status

  • Shipping 包中 MCP 已被编译期剔除,追加该参数无效

3.3 下载并安装 NexusDesktop

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

2.3.3 的安装包按系统选择。

  • Windows 10 / 11(x64)使用 NexusDesktop-windows-amd64-v2.3.3-setup.exe

  • 搭载 Apple 芯片、运行 macOS 12 及以上版本的 Mac 使用 NexusDesktop-darwin-arm64.dmg

  • *-update.zip 供应用内更新使用

Windows 默认按当前用户安装,从开始菜单启动后会进入系统托盘。macOS 启动后在菜单栏显示图标。

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

3.4 启用 NexusDesktop 中转

  1. 右键系统托盘中的 NexusDesktop 图标

  2. 勾选 启用中转服务器(新安装默认关闭,默认端口 6700)

  3. 确认状态行显示当前 UE 工程名,而不是「未连接」

  4. 多开编辑器或独立 Game / DS 时,通过「选择 UE 实例」切换目标进程。列表里缺少目标时,先点「扫描 UE 实例」

NexusDesktop 托盘中的中转开关和 UE 实例菜单
托盘菜单中可以启用中转、扫描或选择 UE 实例。

3.5 复制 MCP 客户端配置

  1. 托盘菜单选择 MCP 客户端配置…

  2. 传输协议选择 Streamable HTTP

  3. 选择实际使用的客户端。Cursor 和 Windsurf 共用一项,CodeBuddy 与 Codex 各有单独选项

  4. 点击「复制」,并记下窗口提示的配置文件位置。Codex 生成 TOML,其余客户端按所选格式生成 JSON

NexusDesktop 生成客户端配置的窗口,Token 已遮挡
客户端配置窗口。按自己的客户端复制对应格式。

Cursor / Windsurf 使用下面的 JSON 结构。已有其他 MCP 服务时,只合并 nexus-unreal 条目。

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

CodeBuddy 在自定义 MCP 配置中使用同样的 URL 和请求头,并在服务条目内加入 "transportType": "streamable-http"。直接复制窗口为 CodeBuddy 生成的条目即可。

Codex 使用 TOML。启用身份验证时,生成的配置包含以下两项。

[mcp_servers.nexus-unreal]
url = "http://127.0.0.1:6700/stream"
http_headers = { Authorization = "Bearer <Token>" }

3.6 粘贴到 AI 客户端

  • Cursor 将条目合并到 ~/.cursor/mcp.json 的 mcpServers。Windows 对应 %USERPROFILE%\.cursor\mcp.json。

  • Windsurf 将条目合并到 Cascade 的 mcp_config.json。CodeBuddy 从「自定义 MCP 配置」粘贴所选条目。

  • Codex 将生成的段落合并到 ~/.codex/config.toml。已有 [mcp_servers.nexus-unreal] 时,更新该段的地址和请求头。

  • 本机默认地址为 http://127.0.0.1:6700/stream。若端口已被占用,请使用 NexusDesktop 配置窗口显示的地址和 Token。

Cursor 的 mcp.json 中已添加 nexus-unreal 服务条目
Cursor 配置文件中的 nexus-unreal 条目。

3.7 验证连接

  1. 重启 MCP 会话或重新打开 AI 面板

  2. 确认 nexus-unreal 显示已连接

  3. UE 默认的 SearchMode 提供 SearchCapabilities、CallCapability、SubmitFeedback。NexusDesktop 另提供 list_unreal_instances 和 connect_unreal_instance,接通 UE 后通常能看到 5 个工具。若只出现后两项,先扫描并连接 UE 实例,再刷新工具列表

  4. 向 AI 输入:「使用 MCP 告诉我当前 UE 编辑器信息。」

  5. 核对 AI 返回的工程名、引擎版本和 PIE 状态是否与当前编辑器一致。下图来自旧版客户端,其中带下划线的 UE 工具名应以当前连接返回的清单为准。

MCP 服务列表中的 nexus-unreal 已连接
客户端显示 nexus-unreal 已连接,并列出可用工具数量。
客户端展开的五个 MCP 工具,截图使用旧版工具名
旧版客户端中的五个工具。当前 UE 工具名见上文。
展开 CodeBuddy 的完整验证对话
CodeBuddy 通过 MCP 返回工程名、引擎版本和 PIE 状态的完整对话
CodeBuddy 返回的工程信息示例。请用自己工程的实际返回值核对。

4. 日常使用

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

常见用法:

  • 「使用 MCP 在 /Game/ 下找到我的角色蓝图,列出它的变量名和类型。如果有重名,先把候选路径给我。」

  • 「使用 MCP 检查当前 PIE 中玩家角色的位置和可见性」

  • 「使用 MCP 检查当前 DS 中指定 Actor、行为树或 GAS 的运行状态」

  • 「使用 MCP 预览这个 Widget 文本的当前值和目标值。等我确认后再写入,读回结果并保存。」

  • 「使用 MCP 查看 Output Log 中最近的 Error」

  • 「使用 MCP 从现在开始记录 Output Log,等我复现问题后,只列出这段时间的 Warning 和 Error。」

  • 「使用 MCP 检查这个蓝图是否绑定了 Lua」(需已安装 NexusLinkExt)

使用注意事项:

  • 查询资产时先用 SearchAsset 获取实际路径,再选相应的读取工具。例如蓝图用 GetAssetBlueprint,已选 Actor 可用 SearchCapabilities 搜 selected actor

  • 删除、重命名、停止 PIE 等破坏性操作默认会触发 NexusDesktop 确认

  • NexusDesktop 的「写入前确认」可设为关闭、仅破坏性操作或全部写操作。在弹窗中选择「本会话总是允许」时,授权仅对当前会话的这项能力生效

  • 托盘选择「暂停 Agent 转发」后,请求会排队,不会立即发往 UE

  • 修改蓝图默认值等受支持的属性时,先用 GetAssetEditPreview 对照当前值和目标值。写入时可用 ExpectedValue 检查前值,用 bVerify 读回结果。保存后检查版本管理中的资产变更


5. 身份验证与危险 Capability

5.1 MCP 身份验证

2.x 默认开启身份验证。同机的 UE 与 NexusDesktop 会读取同一份本机 Token,启用身份验证时,从 NexusDesktop 复制的客户端配置已带 Bearer 请求头。

  • 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 的 /stream 端点时,从 UE 的 NexusLink 偏好设置复制该实例的 Token

  • 跨机时,在提供服务的一端开启局域网绑定。AI 连中转使用中转机的 Token,中转连远程 UE 使用 UE 主机的 Token

  • 不要将 MCP 端口映射到公网

  • 不建议关闭身份验证

5.2 危险 Capability

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

NexusLink 核心:

  • ExecCommand

  • ExecPython

NexusLinkExt(UnLua,安装后才有):

  • EvalRuntimeLua

  • DofileRuntimeLua

要核对当前引擎的 unreal.* API,可用默认开启的只读能力 GetPythonApi 查询名称和签名。

访问模式:

  • 全部禁用:默认。勾选记录保留,但不可调用

  • 每次手动确认:请求须填写至少 24 个字符的 Reason,说明目的、预期效果和需要该能力的原因。每次确认只对本次请求生效。拒绝或超时(默认 90 秒)后应停止。全屏 PIE 看不到窗口时,先退出沉浸模式。独立 Game、Dedicated Server、commandlet 没有确认窗,会直接拒绝

  • 自定义开启:勾选的能力始终允许,不再弹窗

在有视口的 PIE 或独立 Game 中,可在调试面板临时启用一项需要的能力。此设置只在本次进程有效。无视口的 DS 可通过「自定义开启」选择需要的能力。启动参数 -NexusEnableDangerousCaps 会在本次进程允许全部已注册的危险能力。

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

危险 Capability 设置中的三种访问模式
在访问模式下拉框里选择危险能力的确认方式。

6. 高级用法(按需)

PIE / Development 独立包与 DS

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

NexusLink.Mcp panel

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

独立 Game / DS 的启动参数见「3.2 启用 MCP 服务器」。DS 没有视口,用 NexusLink.Mcp status 检查服务。需要从工程代码查询实际状态时,C++ 可调用 UNexusLinkSettings::IsMcpEnabled(),蓝图可使用 Is Mcp Enabled 节点。Shipping 构建中查询返回 false。

PIE 视口中显示运行状态和能力列表的 MCP 调试面板
PIE 视口中的 MCP 调试面板。

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

  • NexusVSCode:Cursor / VSCode 内代理,默认 :6900

  • NexusRider:Rider 代理,默认 :6800

  • 直连 UE:默认 :45000,无代理缓存、写入前确认与暂停能力

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


7. 常见问题

MCP 初始化超时 / 无法连接

依次检查:

  1. UE 已勾选 启用 MCP 服务器,或独立 Game / DS 启动参数已包含 -EnableNexusMcp,进程中显示运行中

  2. NexusDesktop 已启动,托盘已勾选 启用中转服务器

  3. NexusDesktop 状态行显示正确的 UE / Game / DS 实例

  4. AI 配置端口与 NexusDesktop 实际端口一致

  5. Bearer Token 来自 NexusDesktop,且没有复制错误

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

  • 确认启动参数包含 -EnableNexusMcp

  • 确认启动日志中出现 NexusLink MCP 启动信息

  • 在 NexusDesktop 中执行「扫描 UE 实例」

  • 多实例时通过「选择 UE 实例」按进程或端口选择

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

检查 NexusLinkExt 和 UnLua 是否都已启用,重启编辑器,再用 SearchCapabilities 搜索 lua。查询蓝图绑定可用 GetAssetLuaBinding。运行时对象需要 PIE 或独立 Game,且 UnLua 已就绪。精确查询 Lua 执行类能力时,disabled 表示当前访问设置已禁用它。

401 / unauthorized

先确认 AI 连接的是哪一端。经 NexusDesktop 接入时,核对中转地址并重新复制它生成的配置。直连 UE 时,从 UE 偏好设置复制 Token。若仍使用 1.x 中转,请升级到兼容的 2.x 再连接。

工具调用超时

普通同步调用经中转等待约 120 秒会超时。读取资产时可先限定目录和类型。写入发出后若超时或断线,先读回目标资产或运行状态,确认已执行了哪些改动,再决定下一步。已取得 OperationId 的长操作可在原会话通过 GetEditorOperation 查询进度。

修改后磁盘没有变化

部分操作只改内存。确认读回值正确后,调用 SaveAsset,或在支持保存的写入工具上设置 bSaveToDisk=true。蓝图若还需要编译,按该工具的参数表设置 bCompile=true,并检查编译和保存各自的结果。

编辑器正在编译或重启

遇到 EditorBusy 时,先等模态窗口关闭或当前慢任务结束。UE 暂时不可达时,部分只读查询会返回带 _proxy.degraded 的旧快照。等实例重连后重新读取,再据此决定是否写入。

搜不到 GAS / Niagara 等能力

检查宿主工程是否启用了相应插件并已重新编译。再核对连接的进程,独立 Game / DS 只提供运行时能力,编辑资产请连接 Editor 实例。

查看 NexusDesktop 日志

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


8. 参考链接

评论