最近在用 UE5 做关卡原型时最耗时的一步往往不是写功能而是在编辑器里反复创建 Actor、调整位置、验证效果。后来把 Claude Code 和 UE5.8 的 MCP Server 打通之后场景搭建的很多重复操作可以直接用自然语言下指令完成。这篇文章就把我从零开始的完整配置过程和实战经验整理出来覆盖环境准备、插件安装、MCP 接入、实际调用和常见报错排查。新手可以照着逐步操作有经验的开发者也可以直接跳到 MCP 配置和实战部分参考。1. 背景与核心概念1.1 什么是 Claude CodeClaude Code 是 Anthropic 推出的一款终端编程智能体。它不是传统意义上的“代码补全插件”而是一个能直接读取项目文件、执行终端命令、批量修改代码并完成测试的 AI 编程工具。它既能在终端里独立运行也能配合 VS Code 插件使用。它的核心能力包括读取并理解整个项目结构。在多个文件中执行修改。执行终端命令、运行测试。通过 MCP 协议接入外部工具和数据源。对于 UE 开发者来说Claude Code 最大的价值在于它能把“AI 写代码”和“AI 操作编辑器”打通让 AI 不只是生成 C 或蓝图代码片段而是直接参与到关卡搭建、Actor 管理和场景验证中。1.2 什么是 MCP 协议MCPModel Context Protocol模型上下文协议是 Anthropic 发起并开源的一套标准化协议用来统一 AI 模型与外部数据、外部工具之间的交互方式。这里打个比方MCP 相当于 AI 工具圈的“USB-C 接口”。在 MCP 出现之前每个 AI 应用要接入数据库、设计稿、游戏引擎都要单独写一套适配代码而有了 MCP 之后只要实现一套标准协议AI 应用就能直接复用生态里的大量 MCP Server。MCP 的四个核心组成部分组成说明MCP Host宿主程序例如 Claude Code、Claude DesktopMCP Server暴露工具和数据源的独立进程或服务ToolMCP Server 暴露给模型的具体函数包含名称、参数定义和调用逻辑Transport底层通信方式常见的有 stdio、SSE、Streamable HTTP简单理解MCP Server 负责“把能力封装成工具”Claude Code 负责“理解用户意图并调用这些工具”。1.3 Claude Code UE5.8 MCP 能做什么把 Unreal Engine 5.8 编辑器通过 MCP Server 暴露给 Claude Code 后开发者就可以在终端里用自然语言让 Claude 直接操作 UE 编辑器。典型能力包括创建、删除场景中的 Actor。设置 Actor 的位置、旋转、缩放。查询当前关卡中的对象信息。执行引擎控制台命令。在编辑器中输出提示或日志。适合的场景很明确关卡原型搭建、批量摆放资源、AI 驱动的场景批处理、快速搭建 Demo 关卡。对于需要频繁调整场景参数的开发流程这套方案能明显减少手动操作时间。1.4 Skill 与 MCP 有什么区别在 Claude Code 生态里经常有人混淆 Skill 和 MCP。简单说Skill 是一组“做事方法”的文档加脚本它约束 AI 的行为规范告诉模型“这个任务应该按什么步骤做”。Skill 本身不连接外部工具。MCP 是“外部工具接入协议”它解决的是“AI 能调用哪些真实工具”的问题。两者不是替代关系更多是配合使用。实际项目中通常的组合方式是用 Skill 定义任务流程和规范用 MCP 提供执行任务所需的工具能力。2. 环境准备与版本说明2.1 整体架构与版本信息在动手之前先看清楚整条链路的结构Claude CodeMCP Host │ │ MCP 协议 ▼ UE5.8 MCP Server运行在 Unreal Editor 内 │ │ 调用引擎 API ▼ Unreal Engine 5.8 编辑器 / 关卡场景开始之前需要准备以下组件组件作用建议Node.js运行 Claude Code 和大量 MCP ServerLTS 版本Git拉取 UE MCP 插件、管理代码最新稳定版Claude Code CLIMCP Host 主程序npm 全局安装Unreal Engine 5.8目标引擎需要 UE 5.x 系列UE MCP 插件把编辑器暴露成 MCP 工具根据引擎版本选择这里要说明一下本文以 UE 5.8 为示例环境。如果你使用的是 5.4、5.5、5.6 等版本整体流程基本一致重点是插件版本要和引擎版本匹配否则可能出现插件加载失败或工具调用异常。2.2 Node.js 安装与验证Claude Code 本身和很多 MCP Server 都依赖 Node.js 运行所以第一步是安装 Node.js。到 Node.js 官网下载 LTS 版本按系统提示完成安装。安装完成后打开终端验证node -v npm -v两条命令都能输出版本号说明 Node.js 环境正常。如果后续 npm 安装依赖时速度不理想可以配置镜像源。这是合法且常用的加速手段不是必选项npm config set registry https://registry.npmmirror.com配置完成后可以用npm config get registry确认当前源地址。2.3 Git 安装与验证Git 主要用于拉取 UE MCP 插件仓库以及日常代码版本管理。到 Git 官网下载对应操作系统的安装包安装完成后验证git --version出现版本号即安装成功。在 Windows 上安装 Git 时会一并提供 Git Bash后续终端命令在 Git Bash 中执行也可以。2.4 UE5.8 项目准备MCP 插件是放在 UE 项目里的所以需要先准备一个可正常打开的 UE 5.8 项目。如果还没有项目可以先用引擎自带的第三人称或空白模板创建一个。项目创建成功后建议先确认以下几点项目能正常打开编辑器。关卡可以保存项目路径不要包含中文和特殊字符。项目的引擎版本与后续选择的 MCP 插件版本匹配。项目路径这块容易踩坑。很多 UE 工具对中文路径支持不友好建议直接使用纯英文目录。3. 安装 Claude Code CLI3.1 npm 全局安装环境准备好之后先安装 Claude Code。在终端执行npm install -g anthropic-ai/claude-code安装过程会下载 CLI 主程序。这里注意如果 npm 全局目录权限不足在 Linux 或 macOS 上可能需要使用 sudo但更推荐的做法是修正 npm 全局目录权限避免使用管理员权限。3.2 验证安装安装完成后验证是否成功claude --version能看到版本号就说明安装成功。如果提示claude: command not found通常是 npm 全局 bin 目录没有加入 PATH问题排查方法见第 7 节。3.3 登录与鉴权首次在终端运行claude会进入登录流程。你需要准备 Anthropic 账号的登录凭证或者可用的 API Key。登录完成后Claude Code 会在本地生成配置文件。这个文件里面包含鉴权信息不要提交到代码仓库也不要随意发给别人。claude进入交互式终端后可以先用一句简单的话试试基础功能例如让它查看当前目录结构。确认 Claude Code 本身工作正常再进入下一步。4. 配置 UE5.8 MCP Server4.1 获取 UE MCP 插件UE 侧的 MCP 插件目前由社区和厂商共同维护。在 GitHub 搜索 Unreal MCP、Unreal Engine MCP 等关键词能找到多个实现版本。选择插件时建议关注以下几点声明支持 UE 5.x 版本。仓库近期有更新记录。有明确的安装文档和示例。暴露的工具能满足你的项目需求。拿到插件仓库地址后把它克隆到 UE 项目的 Plugins 目录。假设你的项目路径是/path/to/YourUEProjectcd /path/to/YourUEProject git clone 插件仓库地址 Plugins/UnrealMCP这里需要注意不同插件对 UE 版本有要求克隆之前先看一下仓库分支和文档确认它支持 UE 5.8 或者你的引擎版本。4.2 生成项目文件并启用插件插件放进 Plugins 目录之后需要让 UE 识别它。如果你的项目是 C 工程需要重新生成项目文件。右键.uproject文件选择 Generate Visual Studio project files或者直接在 IDE 里重新构建。如果你的项目是纯蓝图工程插件放置好后直接启动编辑器即可。启动编辑器后打开菜单栏的 Edit → Plugins。在搜索框输入 MCP。找到对应插件勾选 Enable。按提示重启编辑器。插件启用后关卡会重新加载。此时留意编辑器右下角或 Output Log 窗口看插件是否正常启动。4.3 启动 MCP 服务不同插件的启动方式略有差异常见的有两种编辑器启动后插件自动启动 MCP 服务。需要通过编辑器工具栏的按钮手动启动。启动成功后插件的日志里通常会打印 MCP Server 地址例如MCP server listening on http://127.0.0.1:8081/mcp把这个地址记下来下一步配置 Claude Code 时会用到。为了让日志更容易查看可以在编辑器的 Window → Developer Tools → Output Log 里打开输出日志面板过滤插件名称相关的关键字。5. 在 Claude Code 中接入 MCP Server5.1 MCP 配置方式Claude Code 支持几种 MCP 配置方式项目级配置在项目根目录创建.mcp.json文件这种方式适合团队共享。用户级配置通过claude mcp命令管理保存到用户目录下。会话内配置在 Claude Code 交互界面中直接添加。推荐使用项目级.mcp.json好处是配置跟着项目走团队成员克隆代码后就能复用同一套 MCP 配置。5.2 编写 .mcp.json 配置文件在项目根目录下创建.mcp.json文件内容如下{ mcpServers: { unreal-editor: { type: http, url: http://127.0.0.1:8081/mcp } } }这里解释一下关键字段mcpServers定义所有 MCP Server 的入口。unreal-editor随意命名用于在 Claude Code 中标识这个服务。type传输类型。新版本 Claude Code 一般使用http早期版本可能是sse具体以claude mcp --help输出为准。urlMCP Server 的地址来源于插件日志。如果你的插件要求通过命令方式启动stdio 传输则配置格式是这样的{ mcpServers: { unreal-editor: { command: npx, args: [-y, 你的MCP启动包名] } } }5.3 使用命令行添加 MCP除了直接写配置文件也可以在 Claude Code 中使用命令添加 MCP Serverclaude mcp add unreal-editor --transport http http://127.0.0.1:8081/mcp添加成功后可以用下面命令查看已配置的 MCP Serverclaude mcp list在交互式中输入/mcp也可以查看已经注册的 MCP 服务和工具列表。5.4 验证连接是否成功配置完成并确认 UE 编辑器中的 MCP 服务正在运行后在 Claude Code 中打开一个新的会话输入/mcp如果能看到类似unreal-editor的服务状态为 connected并且工具列表不为空说明 Claude Code 已经成功连上 UE5.8 MCP Server。首次连接如果失败可以先用浏览器或 curl 访问 MCP 地址确认服务本身是可访问的curl http://127.0.0.1:8081/mcp有响应不代表协议完全正确但至少能排除“服务没起来”这类基础问题。6. 完整实战用自然语言驱动 UE5.8 搭建关卡原型6.1 明确实战目标MCP 连接成功后我们用一个具体案例来验证整条链路。假设当前是一个空白关卡目标是让 Claude 在场景中完成以下操作创建一个 Cube Actor放在位置 (0, 0, 50)。创建一盏 Point Light放在位置 (300, 200, 400)。输出当前场景中所有 Actor 的名称和位置。这里要强调UE 的默认单位是厘米所以 (0, 0, 50) 表示离地 50 厘米。6.2 在 Claude Code 中下达指令在 Claude Code 交互界面输入请在当前 UE 场景中帮我完成以下操作 1. 创建一个 Cube Actor位置设置为 (0, 0, 50) 2. 创建一盏 Point Light位置设置为 (300, 200, 400) 3. 列出当前场景中所有可见 Actor 的名称与位置为了减少误操作建议在指令中明确说明“操作当前打开的关卡”而不是让 AI 自己猜测。6.3 Claude 调用 MCP 工具的过程Claude 收到指令后会根据意图依次调用 MCP Server 暴露的工具。大多数 UE MCP 插件会暴露下面这类工具工具名常见命名作用get_project_info获取当前项目名称、路径、关卡信息spawn_actor在场景中创建指定类型的 Actorget_all_actors获取当前关卡中的 Actor 列表get_actor_info查看指定 Actor 的组件、位置、旋转等信息set_actor_transform设置 Actor 的位置、旋转、缩放delete_actor删除指定 Actorexecute_console_command执行 UE 控制台命令对应上面的流程Claude 可能依次调用get_project_info()确认当前项目。spawn_actor(Cube, [0, 0, 50])创建立方体。spawn_actor(PointLight, [300, 200, 400])创建点光源。get_all_actors()查询场景对象。需要说明的是具体工具名和参数格式因插件而异以上是大多数实现的通用形态以你安装的插件实际暴露的工具为准。6.4 运行结果验证操作完成后回到 UE 编辑器。在 Outliner 面板中应该能看到新创建的 Cube 和 PointLight在 Viewport 中可以看到对应物体。选中 Actor 后可以在 Details 面板中核对 Transform 是否与指令一致。如果场景中看不到物体优先检查是否操作的是当前正在编辑的关卡。Actor 是否被创建到了其他子关卡或 Layer 里。坐标是否超出了可视范围。6.5 提示词使用技巧从实践中总结几条经验一次只做一类操作成功率更高。比如先创建所有 Actor再统一调位置最后再查询。写清单位和坐标UE 默认单位是厘米。修改类操作之前先让 Claude 查询当前状态。批量操作前先小范围验证不要一次性让 Claude 创建上百个对象。7. 常见问题与排查思路配置过程中最容易出问题的环节是环境路径、端口和插件版本。下面整理了一张排查表问题现象常见原因解决思路claude: command not foundnpm 全局 bin 目录没有加入 PATH找到 Node.js 安装路径将全局 bin 目录加入 PATH重新打开终端Claude Code 提示连接 MCP 失败MCP 地址写错或服务未启动确认插件日志中的地址和.mcp.json中的 url 完全一致/mcp中工具列表为空配置文件未被加载重启 Claude Code 会话检查.mcp.json位置是否在项目根目录工具调用超时场景过大或单次操作过多减小批量操作数量分阶段执行Actor 创建成功但 Viewport 看不到坐标异常或关卡不正确在 Outliner 中搜索 Actor 名称确认当前编辑关卡端口被占用上一次编辑器未退出或其他程序占用端口关闭重复的编辑器进程或更换插件监听端口7.1claude: command not found这是最常见的环境问题。原因通常是 npm 全局安装目录没有被加入系统 PATH。在终端执行npm config get prefix会输出 npm 全局目录例如/usr/local或用户目录下的AppData\Roaming\npm。把该目录下的 bin 路径加入 PATH 后重新打开终端即可。7.2 模型名称不匹配的报错很多开发者会把 Claude Code 配置到第三方 API 网关或兼容接口上结果启动时报类似下面的错误xxx is not a model this version of claude code recognizes这个报错的根本原因是当前 Claude Code 版本能识别的模型列表和你配置的模型名不一致。解决办法是检查模型配置相关的环境变量例如ANTHROPIC_MODEL、ANTHROPIC_SMALL_FAST_MODEL把它改成你的网关实际支持的模型名称并和 Claude Code 版本兼容。7.3 排查流程建议遇到问题不要盲目重装按下面顺序排查先看 Claude Code 终端输出的错误日志。再看 UE 编辑器的 Output Log过滤 MCP 插件关键字。用claude mcp list确认配置是否生效。用 curl 直接访问 MCP 地址确认服务是否存活。检查端口是否被占用Windows 上可以用netstat -ano | findstr 8081macOS 或 Linux 上可以用lsof -i :8081。8. 最佳实践与工程建议8.1 配置管理.mcp.json建议纳入代码仓库方便团队成员共享。但要注意如果 MCP Server 需要敏感 Token 或密钥不要把密钥直接写在配置文件里而是通过环境变量注入在.mcp.json的env字段中引用外部环境变量。同时在.gitignore中排除本地特有的配置文件避免个人配置污染团队仓库。8.2 安全边界MCP 的能力本质上是让 AI 能操作编辑器。能力越大越要注意安全边界MCP Server 监听地址尽量使用127.0.0.1不要暴露到公网。不在生产环境或正式发布机上随意挂载 MCP 服务。Claude Code 具备执行终端命令的能力运行前确认指令来源可靠。涉及批量删除、批量修改的指令先在测试关卡验证。8.3 操作稳定性UE 场景操作可能影响编辑器状态建议养成以下习惯执行批量操作前保存当前关卡。复杂操作分阶段进行确认每步结果正常后再继续。如果遇到编辑器崩溃优先复查是不是插件版本和引擎版本不匹配。定期备份关卡文件和项目配置。8.4 把常用流程沉淀成 Skill这是 MCP 接入之后最值得做的工程化动作。当你发现某些指令组合经常重复比如“创建灯光模板”“布置测试关卡”可以把这些流程整理成 Skill 文档让 Claude 按照固定步骤执行。这样一来Skill 负责定义流程规范MCP 负责提供工具能力两者配合起来AI 才能真正稳定地完成复杂任务。8.5 关注 MCP 生态的通用能力UE5.8 MCP 只是 MCP 生态中的一个场景。在项目实践中MCP 同样可以连接设计工具、测试工具、数据库等。比如Figma MCP让 AI 读取设计稿信息。Playwright MCP让 AI 操作浏览器进行自动化测试。Unity MCP在 Unity 中实现类似的 AI 操作。蓝湖 MCP连接设计交付平台。掌握 MCP 的配置思路后其他 MCP Server 的接入基本都是同一套流程启动服务配置.mcp.json或claude mcp add验证工具列表开始调用。9. 总结与下一步学习到这里一条完整的 Claude Code UE5.8 MCP 链路已经跑通了从 Node.js、Git 环境准备到 Claude Code 安装登录再到 UE MCP 插件配置和.mcp.json接入最后通过自然语言在编辑器里完成 Actor 创建和查询。如果你照着本文成功跑通了最简单的场景下一步可以按这个顺序继续深入做一个批量摆放静态网格的例子验证大规模操作。把常用操作模板化成 Skill让 Claude 可以重复执行。读一下 UE MCP 插件的源码尝试为插件扩展自定义工具。研究 MCP 协议中的 tool schema 定义了解如何设计更复杂的参数结构。遇到问题的时候优先检查两端日志终端里看 Claude Code 输出编辑器里看 Output Log。绝大多数连接问题都能用这个方法定位。如果本文对你有帮助欢迎收藏备用也欢迎在评论区分享你在 UE5.8 上接入 MCP 的真实踩坑经历。