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。
需要开启两层服务:
UE:启用 MCP 服务器
NexusDesktop:启用中转服务器
任一层关闭都会导致 AI 无法连接。端口冲突时会自动顺延,以界面显示的实际端口为准。
本机只开一个中转。NexusDesktop、NexusRider、NexusVSCode 不要同时启用,否则会重复扫描并连接同一个 UE。
3. 开启步骤
推荐流程:安装 NexusLink → UE 启用 MCP → 安装 NexusDesktop → 启用中转 → 复制 MCP 配置 → 验证连接。
3.1 安装 NexusLink 插件
工程已集成插件时,可直接前往「3.2 启用 MCP 服务器」。
从 NexusLink Releases 下载插件包
nexus-mcp-unreal-2.3.7.zip把压缩包内的
NexusLink/放入项目的Plugins/,确认路径为Plugins/NexusLink/NexusLink.uplugin打开工程,在 Edit → Plugins → Developer → NexusLink 中启用插件
重启编辑器
启用插件不会启动 MCP。HTTP / WebSocket 默认关闭,下一步再勾选「启用 MCP 服务器」。
插件包含运行时模块 NexusLink 和编辑器模块 NexusLinkEditor。Development / DebugGame 独立 Game 和 DS 只加载运行时模块。Shipping 在编译时剔除 MCP 服务。需要仓库里的 GAS、行为树复测或 Trace 对比脚本时,从同版本 Release 另取源码包中的 tools/。
可选:NexusLinkExt(UnLua)
核心包不含 UnLua。需要蓝图 Lua 绑定或运行时 Lua 时再安装:
从 NexusLinkExt Releases 下载
nexus-mcp-ext-1.1.2.zip把压缩包内的
NexusLinkExt/放入项目的Plugins/在 .uproject 中启用 NexusLinkExt,并确认工程已启用 UnLua
重启编辑器,用
SearchCapabilities搜索lua
未启用 UnLua 时,扩展能力无法注册。HotReloadRuntimeLua 需要 UnLua 2.x。EvalRuntimeLua、DofileRuntimeLua 默认禁用,访问模式仍在 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
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 中转
右键系统托盘中的 NexusDesktop 图标
勾选 启用中转服务器(新安装默认关闭,默认端口 6700)
确认状态行显示当前 UE 工程名,而不是「未连接」
多开编辑器或独立 Game / DS 时,通过「选择 UE 实例」切换目标进程。列表里缺少目标时,先点「扫描 UE 实例」

3.5 复制 MCP 客户端配置
托盘菜单选择 MCP 客户端配置…
传输协议选择 Streamable HTTP
选择实际使用的客户端。Cursor 和 Windsurf 共用一项,CodeBuddy 与 Codex 各有单独选项
点击「复制」,并记下窗口提示的配置文件位置。Codex 生成 TOML,其余客户端按所选格式生成 JSON

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。

3.7 验证连接
重启 MCP 会话或重新打开 AI 面板
确认 nexus-unreal 显示已连接
UE 默认的
SearchMode提供SearchCapabilities、CallCapability、SubmitFeedback。NexusDesktop 另提供list_unreal_instances和connect_unreal_instance,接通 UE 后通常能看到 5 个工具。若只出现后两项,先扫描并连接 UE 实例,再刷新工具列表向 AI 输入:「使用 MCP 告诉我当前 UE 编辑器信息。」
核对 AI 返回的工程名、引擎版本和 PIE 状态是否与当前编辑器一致。下图来自旧版客户端,其中带下划线的 UE 工具名应以当前连接返回的清单为准。


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 核心:
ExecCommandExecPython
NexusLinkExt(UnLua,安装后才有):
EvalRuntimeLuaDofileRuntimeLua
要核对当前引擎的 unreal.* API,可用默认开启的只读能力 GetPythonApi 查询名称和签名。
访问模式:
全部禁用:默认。勾选记录保留,但不可调用
每次手动确认:请求须填写至少 24 个字符的
Reason,说明目的、预期效果和需要该能力的原因。每次确认只对本次请求生效。拒绝或超时(默认 90 秒)后应停止。全屏 PIE 看不到窗口时,先退出沉浸模式。独立 Game、Dedicated Server、commandlet 没有确认窗,会直接拒绝自定义开启:勾选的能力始终允许,不再弹窗
在有视口的 PIE 或独立 Game 中,可在调试面板临时启用一项需要的能力。此设置只在本次进程有效。无视口的 DS 可通过「自定义开启」选择需要的能力。启动参数 -NexusEnableDangerousCaps 会在本次进程允许全部已注册的危险能力。
只有确认不存在专用 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。

其他中转方式仅在有明确需求时使用:
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 是否都已启用,重启编辑器,再用 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 日志
托盘菜单选择 打开日志目录。反馈问题时请附上相关时间段日志,并先检查其中是否含需要脱敏的信息。

评论