之前试过让 AI 直接操作虚幻引擎编辑器踩了不少坑要么插件版本对不上要么 AI 只能给出建议、没法真正读取关卡信息更别说生成 Actor。最近在 UE5.8 环境里重新梳理了一套基于 MCPModel Context Protocol的接入方案思路理顺之后一条最小链路很快就能跑起来。本文会从零开始讲清楚 MCP 在虚幻引擎里的使用方式并提供一个可以照着复制的完整示例新手也能看懂有基础的开发者可以直接跳到第 4 节看代码。1. MCP 是什么先搞懂概念1.1 为什么突然都在聊 MCPMCP 是 Model Context Protocol 的缩写翻译过来是“模型上下文协议”。它最早由 Anthropic 在 2024 年底推出定位是 AI 模型与外部工具、数据源之间的开放通信协议。简单理解MCP 想解决的是“AI 应用和各个工具之间集成太碎片化”的问题。在没有 MCP 之前每个 AI 应用要去对接不同工具通常都要写不同的适配代码对接文件系统写一套对接数据库写一套对接游戏引擎又要单独开发一套插件。工具越多集成代码越难维护。MCP 的出现相当于定义了一个标准“插座”AI 应用通过同一个协议去连接支持 MCP 的服务端切换工具时不需要重写通信逻辑只需要知道对方暴露了什么能力。这个思路和 USB-C 接口很像。以前每个设备都要专门的线现在大家共用一种标准协议设备之间互通的成本大幅下降。对虚幻引擎开发者来说最大的价值是你可以把引擎编辑器里的常见操作暴露成一个个“工具”让 AI 通过自然语言调用这些工具从而真正辅助完成关卡搭建、资产整理、场景分析等任务。1.2 MCP 的三类角色与核心流程MCP 体系里通常有三个角色搞懂这三个角色就等于搞懂了 MCP 的骨架。角色代表职责MCP HostClaude Desktop、Cline、Cherry Studio 等 AI 客户端运行 AI 模型向用户展示交互界面MCP ClientHost 内部负责通信的组件与 MCP Server 建立连接收发 JSON-RPC 消息MCP Server我们编写的 Python 服务进程定义并实现工具、资源、提示词供 AI 调用一次完整的调用大致是这样的用户向 AI 提问AI 发现当前问题可能需要外部工具于是让 MCP Client 向 Server 查询“你有哪些工具”Server 返回工具清单和参数定义AI 根据工具定义生成调用请求Server 执行实际操作把结果返回给 AIAI 再把结果整理成用户能读懂的回复。整个通信基于 JSON-RPC 2.0内容结构化AI 不需要猜测工具接口因为参数格式已经在工具定义里写清楚了。这就是 MCP 能稳定支撑 AI 实操的原因。1.3 MCP 与 UE 的关系UE5.8 里的定位需要先说明一个关键点截止到本文写作时的通用做法UE5.8 本身并不是一个 MCP Server引擎内部也没有直接内置完整的 MCP 服务端。也就是说你不能在项目设置里勾个开关就让 Claude 直接连接 UE5.8。MCP 和 UE 之间还缺一个“翻译层”。这个翻译层通常是一个独立运行的 MCP Server 进程它负责两件事面向 AI 客户端按照 MCP 协议暴露工具。面向 UE通过 Unreal Editor Python API 或命令行脚本实际执行引擎操作。为什么用 Python 做翻译层最方便因为 UE 官方长期提供 Python Editor Script Plugin编辑器里的大部分批量操作、资产管理、Actor 遍历能力都能通过 Python 脚本调用。而 MCP 的 Python SDK 也已经很成熟写一个服务端进程只需要几十行代码。所以本文的核心思路可以总结成一句话用 MCP Server 把 UE 编辑器能力封装成工具再让 AI 客户端通过自然语言调用这些工具最终得到可以直接落地到项目里的操作结果。2. 环境准备与版本说明2.1 本文示例的软件环境清单先把环境说清楚避免后面复现时出现版本不匹配导致的报错。下表是作者本机的环境你的版本可以不完全一致但逻辑相同。软件版本 / 说明虚幻引擎UE5.8不同小版本菜单略有差异操作系统Windows 11macOS / Linux 也可路径写法不同Python3.10 或更高建议 3.11 / 3.12MCP Python SDK使用mcp库安装时带上cli扩展AI 客户端Claude Desktop、Cline 或其他支持 MCP 的客户端编辑器插件Python Editor Script Plugin 必须启用如果你的 UE 是 5.4、5.5 这类更早的版本下面的 UE Python API 大体兼容但个别类名和方法可能略有差异遇到报错时优先在官方 Python API 文档里搜索对应方法即可。2.2 启用 UE 编辑器 Python 插件UE 默认不会把 Python 脚本功能完全打开第一步要确认插件状态。打开 UE5.8 编辑器进入 Edit → Plugins在搜索框输入Python找到 Python Editor Script Plugin确认右边的 Enabled 复选框被勾选。如果之前没有启用勾选后会提示重启编辑器按提示操作即可。重启之后建议顺便确认一下 Python 是否真的可用。可以在菜单栏查看有没有 Python 相关面板或者直接在下方的 Output Log 窗口的命令行里输入下面这行unreal.SystemLibrary.get_engine_version()如果返回引擎版本信息说明 Python 插件已经正常工作。这里有一个很容易忽略的点Python Editor Script Plugin 启用的是“编辑器内 Python 脚本”而不是让你在外部直接调一个 Python 解释器操作引擎。外部进程的操作需要借助 UE 的命令行参数或者编辑器内部开启的通信端口第 4 节会演示具体方案。2.3 安装 Python 与 MCP SDKUE 5.8 通常自带一个内部 Python 环境但 MCP Server 是独立进程需要系统里有可用的 Python。先检查系统 Pythonpython --version如果提示找不到命令需要先安装 Python 3.10并勾选 Add Python to PATH。接着安装 MCP Python SDKpip install mcp[cli]安装完成后可以快速验证版本python -m mcp --version看到版本号说明 SDK 已就绪。后续编写 MCP Server 时只需要导入mcp.server.fastmcp模块。3. MCP 在虚幻引擎中的工作原理解析3.1 整体架构三方如何协作先把完整链路画出来方便理解后面每一步代码的作用AI 客户端 (Claude Desktop / Cline) ↓ MCP 协议stdio MCP Server (Python 进程) ↓ subprocess 调用 UE 命令行 UE5.8 编辑器进程 (-ExecutePythonScript) ↓ Unreal Editor Python API 关卡场景 / 资产 / 蓝图数据AI 客户端只和 MCP Server 通信MCP Server 只负责把请求翻译成 UE 能理解的操作UE 返回的结果再由 Server 整理成结构化数据最终交还给 AI。这种分层设计的优点很明显AI 客户端不需要知道 UE 的具体 APIUE 侧也不需要关心哪个 AI 在调用它。只要 MCP Server 稳定理论上任何支持 MCP 的客户端都能直接复用同一套引擎操作能力。3.2 核心消息格式与工具调用流程MCP 的通信格式是 JSON-RPC 2.0。与 UE 集成时你需要重点关注两个方法tools/listAI 询问 Server 当前支持哪些工具。tools/callAI 发起具体工具调用并传入参数。当我们用 FastMCP 定义工具时SDK 会自动处理这两个方法。你只需要关心三件事工具叫什么名字。工具接收什么参数。工具执行后返回什么内容。例如下面这个工具定义mcp.tool() def list_level_actors() - str: 返回当前关卡中所有 Actor 的名称、类型和位置。 return ...SDK 会把函数名、docstring 和参数类型转成 JSON SchemaAI 看到这个 Schema 就知道该调用什么、传什么参数。这也是为什么 MCP 工具天然适合 AI 使用因为它把接口描述和接口实现绑定在同一个函数上。3.3 为什么选择 Python 脚本作为 UE 与 AI 之间的桥梁可能有读者会问为什么不直接写一个 UE 插件去实现 MCP Server从技术上是可行的但代价很高你需要用 C 实现 JSON-RPC 解析、stdio 或 HTTP 通信、线程管理还要处理引擎生命周期开发成本远超普通需求。而 UE 官方已经提供了相当完整的 Python Editor Script Plugin大部分编辑器操作都能用 Python 完成比如遍历、创建、删除 Actor。管理资产导入、移动、重命名、删除。读写 UE 编辑器日志、执行菜单命令。调用蓝图函数、操作关卡和子关卡。MCP Python SDK 同样成熟因此用 Python 写一个独立服务进程再通过 subprocess 或 HTTP 接口驱动 UE是目前性价比最高的方案。需要提醒的是用 subprocess 调用 UE 命令行完成一次操作过程相对慢因为要启动引擎进程。如果你的目标是“AI 实时操控正在打开的编辑器”比较合理的做法是在编辑器里启动一个 Python HTTP 服务让 MCP Server 通过 HTTP 调用编辑器 API。本文为了演示最小链路先使用命令行脚本方式它更适合批处理和自动化验证场景。4. 完整实战10 分钟跑通 UE5.8 MCP 最小链路“10 分钟”这里说一下真实体验熟悉概念和代码最快只要 10 分钟但第一次运行 UE 命令行启动引擎进程可能需要几分钟。不要因为第一次启动慢就以为是卡死了后面会讲怎么判断状态。4.1 创建项目结构与依赖建议单独建一个目录存放 MCP 相关文件不要直接塞进 UE 项目目录方便日常维护。示例结构如下ue5-mcp-demo/ ├── server.py ├── requirements.txt └── ue_scripts/ ├── list_actors.py ├── list_assets.py └── get_version.pyrequirements.txt内容mcp安装依赖pip install -r requirements.txt4.2 编写 MCP Server下面是最关键的server.py。它基于 FastMCP 定义三个工具每个工具都通过 UE 命令行执行脚本然后读取脚本写出的 JSON 结果。import json import os import subprocess import tempfile from mcp.server.fastmcp import FastMCP # 改成你本机的 UE5.8 安装路径 UE_EDITOR_CMD rC:\Program Files\Epic Games\UE_5.8\Engine\Binaries\Win64\UnrealEditor-Cmd.exe # 改成你的 uproject 文件绝对路径 UE_PROJECT rD:\UEProjects\MyDemo\MyDemo.uproject # UE 脚本目录 UE_SCRIPTS os.path.join(os.path.dirname(os.path.abspath(__file__)), ue_scripts) # 临时输出目录 OUTPUT_DIR tempfile.gettempdir() mcp FastMCP(ue5-mcp-demo) def _run_ue_script(script_name: str) - str: script_path os.path.join(UE_SCRIPTS, script_name) output_path os.path.join(OUTPUT_DIR, fue_{script_name.replace(.py, )}.json) os.environ[UE_MCP_OUTPUT] output_path cmd [ UE_EDITOR_CMD, UE_PROJECT, -unattended, -nullrhi, -nop4, f-ExecutePythonScript{script_path}, ] subprocess.run(cmd, checkTrue, capture_outputTrue, timeout300) return output_path def _read_output(output_path: str) - str: with open(output_path, r, encodingutf-8) as f: data json.load(f) return json.dumps(data, ensure_asciiFalse, indent2) mcp.tool() def list_level_actors() - str: 返回当前关卡中所有 Actor 的名称、类型和位置。 try: out _run_ue_script(list_actors.py) return _read_output(out) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse) mcp.tool() def list_asset_names(folder_path: str /Game) - str: 列出指定资产目录下的所有资产名称。 try: out _run_ue_script(list_assets.py) return _read_output(out) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse) mcp.tool() def get_engine_version() - str: 获取引擎版本号和当前项目名称。 try: out _run_ue_script(get_version.py) return _read_output(out) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse) if __name__ __main__: mcp.run()关键点说明UE_EDITOR_CMD和UE_PROJECT是必须修改的两项常量不要直接复制运行。-unattended表示无交互模式避免弹出对话框阻塞命令。-nullrhi绕过图形设备初始化官方文档和常见 CI 场景中经常使用。-ExecutePythonScript会执行指定 Python 文件。os.environ[UE_MCP_OUTPUT]用于把输出文件路径传给 UE 侧的 Python 脚本。工具函数返回的是字符串AI 拿到后自行解析 JSON。4.3 编写 UE 端 Python 工具脚本在ue_scripts目录下创建list_actors.pyimport json import os import unreal actors unreal.EditorLevelLibrary.get_all_level_actors() items [] for actor in actors: items.append({ name: actor.get_actor_label(), class: actor.get_class().get_name(), location: str(actor.get_actor_location()), }) output_path os.environ.get(UE_MCP_OUTPUT, os.path.join(os.environ[TEMP], ue_mcp_output.json)) with open(output_path, w, encodingutf-8) as f: json.dump(items, f, ensure_asciiFalse, indent2)创建list_assets.pyimport json import os import unreal assets unreal.EditorAssetLibrary.list_assets(/Game, recursiveTrue) output_path os.environ.get(UE_MCP_OUTPUT, os.path.join(os.environ[TEMP], ue_mcp_output.json)) with open(output_path, w, encodingutf-8) as f: json.dump(assets, f, ensure_asciiFalse, indent2)创建get_version.pyimport json import os import unreal info { engine_version: unreal.SystemLibrary.get_engine_version(), project_name: unreal.SystemLibrary.get_game_name(), } output_path os.environ.get(UE_MCP_OUTPUT, os.path.join(os.environ[TEMP], ue_mcp_output.json)) with open(output_path, w, encodingutf-8) as f: json.dump(info, f, ensure_asciiFalse, indent2)如果你使用的 UE API 名称不同比如某个版本的EditorLevelLibrary方法被标记为废弃可以打开 UE 官方 Python API 页面搜索EditorLevelLibrary以你当前版本提供的接口为准。4.4 配置 AI 客户端接入以 Claude Desktop 为例在配置文件claude_desktop_config.json中加入{ mcpServers: { ue5mcp: { command: python, args: [D:\\ue5-mcp-demo\\server.py] } } }如果你用 Cline、Cherry Studio 这类客户端一般在设置界面的 MCP Servers 处添加命令填python参数填D:\ue5-mcp-demo\server.py效果相同。保存配置后重启客户端正常情况下客户端会自动拉起 MCP Server。你可以打开 MCP 管理窗口确认ue5-mcp-demo已经连接并且工具列表里能看到上面三个工具。有一点要注意Windows 下的路径最好写双反斜杠\\或者使用正斜杠/避免 JSON 解析失败。4.5 运行验证让 AI 读取关卡信息打开任意一个 UE5.8 项目手动放一个 Cube 或者任意 StaticMesh Actor保存关卡关闭编辑器。然后在 AI 客户端里发送这样一句话请调用引擎版本工具告诉我当前项目的引擎版本。AI 会调用get_engine_version触发 MCP Server 执行 UE 命令行脚本。第一次执行时UE 会把整个编辑器进程启动一遍耗时可能达到几分钟耐心等待。也可以用更直观的方式验证请列出当前关卡中的所有 Actor。AI 调用list_level_actors后最终会返回 JSON 数组包含 Actor 名称、类型和位置。4.6 预期输出与结果说明get_engine_version的预期输出类似{ engine_version: 5.8.0-..., project_name: MyDemo }list_level_actors的预期输出类似[ { name: SM_House, class: StaticMeshActor, location: (X120.000000,Y200.000000,Z0.000000) }, { name: LightSource_0, class: DirectionalLight, location: (X0.000000,Y0.000000,Z1000.000000) } ]如果你看到一个包含error字段的 JSON说明 UE 命令行执行失败可能是路径配置错误、项目无法打开、或者 Python 脚本内部报错。下一步就是排查环节。5. 常见问题与排查思路5.1 高频报错对照表下面整理了 UE5.8 接入 MCP 时最容易遇到的几类问题。问题现象常见原因解决思路客户端提示无法连接 MCP ServerMCP SDK 未安装server.py路径错误python命令不存在先手动运行python D:\\ue5-mcp-demo\\server.py看是否报错工具调用后返回ModuleNotFoundError: No module named mcp当前 Python 环境不是安装 SDK 的环境使用完整 Python 路径或用py -3.11指定版本UE 命令行模式没有任何输出-ExecutePythonScript指向的脚本路径不正确或者项目路径写错检查UE_PROJECT和UE_SCRIPTS之间的路径拼接执行脚本后输出文件不存在UE 脚本内部抛异常比如 API 名称错误查看 UE 日志Saved/Logs搜索 Python Error返回空数组但不是错误当前关卡确实没有 Actor先在编辑器里放几个 Actor 再试第一次启动等待时间过长UE 首次以命令行模式启动需要编译着色器等模块观察任务管理器是否有 UnrealEditor 进程等待 5 分钟以上Windows 路径解析失败JSON 配置中的反斜杠没有转义统一使用双反斜杠或正斜杠5.2 标准排查顺序如果链路不通建议按下面的顺序排查不要盲目改代码。直接运行 MCP Serverpython D:\ue5-mcp-demo\server.py。如果进程能启动并等待输入说明 SDK 安装正常。手动执行 UE 命令行脚本跳过 MCP 层。打开 CMD手动拼一遍_run_ue_script中的命令观察是否有报错输出。查看 UE 日志文件路径在项目目录下的Saved/Logs/MyDemo.log。搜索Python、Error关键字。确认输出文件是否生成如果生成但内容为空检查unreal.EditorLevelLibrary.get_all_level_actors()是否在你当前 UE 版本返回空列表。确认 AI 客户端配置已经重新加载部分客户端改完claude_desktop_config.json需要完全退出再启动。5.3 一个容易忽略的问题编辑器状态冲突如果在运行 MCP 工具时UE 编辑器已经打开并占用了同一个项目可能会出现项目锁冲突导致命令行模式启动失败。建议先关闭当前编辑器实例再让 MCP Server 去启动命令行进程。如果你希望“编辑器保持打开同时让 AI 实时操作”就要换成 HTTP 方式在编辑器里运行一个 Python HTTP 服务MCP Server 把请求转发到 localhost 端口。这是下一步进阶很自然的方向。6. 最佳实践与工程建议6.1 安全边界不要让 AI 执行任意代码MCP 的强大之处是 AI 可以直接触发引擎操作但反过来也意味着风险。如果工具定义里提供了一个“执行任意 Python 字符串”的接口AI 就可以在编辑器里做任何事包括批量删除资产、修改项目配置。这不是危言耸听而是真实存在的安全边界问题。更稳妥的做法是只向 AI 暴露有明确目的、参数受限的工具。比如list_level_actors不需要参数list_asset_names只接受文件夹路径。假如未来要增加“创建 Actor”工具也应当固定允许创建的类白名单不要接收全量类名。6.2 工具粒度与命名规范工具命名建议遵循“动词 对象”格式例如list_level_actorsspawn_static_meshdelete_actor_by_labelimport_asset_from_path命名尽量让 AI 一看就懂。工具描述也要写得具体比如“列出当前关卡中的所有 Actor包括名称、类型和位置”这样 AI 判断是否调用该工具时更准确。工具职责要单一。一个工具只做一件事避免出现“读取 Actor 并顺便创建资产”这类混合逻辑否则 AI 在调用时容易传错参数。6.3 超时、日志与异常处理UE 命令行启动很慢subprocess.run的timeout参数不要设置得太小。本地第一次启动建议 300 秒后续可以适当缩短到 120 秒。MCP Server 工具内部一定要捕获异常并把错误信息结构化返回给 AI。如果让异常直接抛到协议层AI 客户端可能只显示“调用失败”而看不到具体原因排查效率很低。建议在 Server 端增加日志文件logging.basicConfig( filenameue_mcp_server.log, levellogging.INFO, format%(asctime)s %(levelname)s %(message)s )每次工具调用都记录时间、工具名、耗时和结果摘要。后面调试 AI 行为时这份日志价值非常大。6.4 多项目与多人协作时的配置管理不要把server.py里的UE_EDITOR_CMD和UE_PROJECT写死并提交到公共仓库。建议把这三个配置抽成环境变量或配置文件UE_EDITOR_CMD os.environ.get(UE_EDITOR_CMD, DEFAULT_UE_EDITOR_CMD) UE_PROJECT os.environ.get(UE_PROJECT_PATH, DEFAULT_PROJECT_PATH)这样每个开发者只需在自己环境中设置变量不需要改动共享代码。涉及生产环境或正式项目时所有工具的变更应该先在测试场景验证并确保项目有版本控制备份。删除、移动资产这类危险操作最好设计确认环节比如先输出将要操作的对象列表再执行实际变更。7. 总结与学习路线这篇文章从概念讲到实现核心收获可以归纳为三点。第一MCP 解决的是 AI 与工具之间集成碎片化的问题在 UE 场景中我们通常用 Python 写一个独立 Server把引擎能力封装成标准工具。第二最小可行链路是“AI 客户端 → MCP Server → UE 命令行 → Python 脚本 → JSON 结果”先跑通这条链路再考虑扩展更多工具。第三工具设计要注意安全边界和故障排查不让 AI 执行任意代码同时把日志和超时机制准备好。下一步建议按顺序尝试这些方向扩展工具增加spawn_actor、rename_actor、import_asset等实用工具。改用 HTTP 通信在 UE 编辑器内开启 Python HTTP 服务这样不需要反复启动引擎进程AI 可以实时操作当前打开的关卡。结合蓝图研究如何通过 Python 调用蓝图函数让 AI 辅助调整蓝图参数。搭建资产批处理工具让 AI 根据规则批量整理项目中的材质、贴图和静态网格体。如果你想快速度过入门阶段建议直接把第 4 节的server.py和ue_scripts复制出来改成自己的项目和编辑器路径先跑通一个读关卡列表的工具。跑通之后你会明显感觉到AI 从“只会聊天”变成“能碰引擎数据”这套链路值得继续投入时间研究。