Claude Code 怎么控制 Unreal Engine？Epic 官方插件安装、MCP 连接与安全设置（UE5 实操）

先说结论：让 Claude Code 控制虚幻引擎（UE5），要两边一起配：编辑器里打开 Unreal MCP 服务，Claude Code 里装 Epic 的官方插件 unreal-engine-skills-for-claude-code。插件负责教 Claude Code 怎么用 UE 的工具，真正干活的是编辑器里的 MCP 服务，所以编辑器必须开着。

我们用 AICodeWith 的 Key 在 Claude Code 2.1.302 上实测了 Claude Code 这一端：

• 加官方插件市场 2.2 秒，装插件 2.5 秒，全程没有要求登录 Anthropic 账号
• 装好后插件里的 3 个技能和 1 个启动钩子都正常加载，在含 .uproject 的目录里打开 Claude Code，它能认出这是 Unreal 项目
• 编辑器没开的时候，/mcp 里的 unreal-mcp 显示为连接失败，但不影响 Claude Code 正常启动

获取 API Key →

这个插件是什么

unreal-engine-skills-for-claude-code 是 Epic Games 出的 Claude Code Unreal Engine 插件，MIT 许可，收录在 Anthropic 的官方插件市场 claude-plugins-official 里。截至 2026 年 10 月 18 日，最新版本是 3.1.1（9 月 17 日更新）。

很多人搜的「Unreal MCP 怎么连」「虚幻引擎 MCP」，说的就是下表里编辑器端的那一半。整套方案由两部分配合工作：

Epic 在 Unreal Engine 5.8 的文档《Unreal MCP in Unreal Editor》里介绍了 Unreal MCP，并标注为实验性功能：很多功能还不完整，接口和数据格式随时可能变。正式项目里用之前要心里有数。

前置条件

1. Unreal Editor，并且能启用 ModelContextProtocol（Unreal MCP）和 AllToolsets 两个插件
2. Claude Code，已经配好 API（下一节）
3. 能用的 bash：macOS、Linux 自带；Windows 要装 Git for Windows（自带 Git Bash）或者在 WSL 里运行 Claude Code

第一步：给 Claude Code 配置 API

把地址和 Key 写进全局配置文件 ~/.claude/settings.json 的 env 里，不用在终端里 export：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aicodewith.ai",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
  }
}

更多配置方式见《Claude Code 如何接入第三方 API》。操作编辑器这类多步骤任务，用哪个模型合适可以看《Claude Code 用哪个模型》。

第二步：在编辑器里打开 Unreal MCP

启用两个插件

在 UE 编辑器里打开 Edit > Plugins：

1. 搜索 Unreal MCP，勾选 Enabled；
2. 搜索 All Toolsets，勾选 Enabled；
3. 按提示重启编辑器。

AllToolsets 一定要开。Unreal MCP 只负责服务和连接，工具都在 AllToolsets 里。只开 Unreal MCP 的话，服务能启动，但一个工具都没有。只想开放部分工具，也可以不开 AllToolsets，单独启用需要的工具集插件。

启动 MCP 服务

打开编辑器控制台（默认按反引号键），输入：

ModelContextProtocol.StartServer

服务默认监听 http://127.0.0.1:8000/mcp，在 Output Log 里能看到启动信息。8000 端口被占用的话，在命令后面加一个别的端口号，比如：

ModelContextProtocol.StartServer 8010

不想每次手动启动，可以在 Edit > Editor Preferences > General > Model Context Protocol 里打开 Auto Start Server，端口和路径也在这里改。

生成 .mcp.json

在控制台输入：

ModelContextProtocol.GenerateClientConfig ClaudeCode

它会生成 Claude Code 用的 .mcp.json，内容是这样的：

{
  "mcpServers": {
    "unreal-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

文件写在哪里取决于你的引擎：从 Epic 启动器装的引擎，写在 .uproject 旁边；源码编译的引擎，写在包含 Engine/ 的工作区根目录。之后在这个目录里启动 Claude Code。改过端口或路径后要重新运行一次这条命令，它会合并更新，不会覆盖别的配置。

第三步：在 Claude Code 里装插件

在 Claude Code 会话里运行：

/plugin install unreal-engine-skills-for-claude-code@claude-plugins-official

如果提示找不到插件或者没有这个插件市场，先把官方插件市场加进来，再装一次：

/plugin marketplace add anthropics/claude-plugins-official

也可以不进会话，直接在终端里用命令装：

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install unreal-engine-skills-for-claude-code@claude-plugins-official

我们在一台全新的机器上直接运行 claude plugin install，报了 not found in marketplace "claude-plugins-official"，因为新机器还没打开过交互会话，官方插件市场没有注册。先运行 marketplace add 之后，2.5 秒就装好了。

团队统一安装

把下面这段提交到项目的 .claude/settings.json，同事信任这个项目目录时，Claude Code 会提示他们自动安装：

{
  "enabledPlugins": {
    "unreal-engine-skills-for-claude-code@claude-plugins-official": true
  }
}

这是项目级配置，只放插件开关。API 地址和 Key 还是各自写在自己的全局 ~/.claude/settings.json 里，不要提交到仓库。

第四步：验证连接

按这个顺序检查：

1. 编辑器开着，并且已经运行过 ModelContextProtocol.StartServer；
2. 在 Claude Code 里输入 /plugin，Installed 标签页里能看到 unreal-engine-skills-for-claude-code；
3. 输入 /mcp，能看到 unreal-mcp；
4. 让它干点简单的事试试，比如：List all actors in the current level（列出当前关卡里的所有 Actor）。

第一次在项目目录里打开 Claude Code 时，它会问要不要使用 .mcp.json 里的 unreal-mcp。默认选项是“Continue without using this MCP server”，要手动选 Use this MCP server，不然 /mcp 里就不会连它。

我们的实测结果（机器上没有 UE 编辑器，所以 MCP 服务是关着的）：

claude-code-unreal-mcp-status

编辑器打开、服务启动之后，不用重启 Claude Code，在 /mcp 里选中 unreal-mcp，点 Reconnect 就能重连。

能做什么

插件说明里写的是：通过 30 多个工具集、几百个工具覆盖编辑器的大部分功能。按类别大致是：

这么多工具不会一次全塞进上下文。Unreal MCP 默认开着“工具搜索”：只暴露 list_toolsets、describe_toolset、call_tool 三个工具，Claude Code 用到哪类再去查哪类，省上下文。想一次性注册全部工具，可以把设置里的 bEnableToolSearch 关掉。

插件里的技能是怎么被触发的，可以看《Claude Code Skill 怎么用》；其他官方插件的装法，见《Claude Code 岗位插件怎么装》。

安全设置

装了这个插件，相当于让 Claude Code 实时操作你正在运行的编辑器。Epic 在插件说明里专门写了几条提醒：

1. execute_tool_script 能运行任意 Python。这个工具在编辑器进程里执行 Python，能调所有工具、读写磁盘上的项目和资产。每次调用都当成高权限操作看待。
2. 别和 --dangerously-skip-permissions 一起用。这个参数会去掉每次调用工具前的确认，Claude Code 可以不经同意就改编辑器、跑 Python，一个提示词写歪了，可能在你发现之前就改了一大片。真要用，就只做只读或范围很小的任务，最好在一个可以随便删的测试项目里。
3. 长时间操作前先提交版本库。MCP 工具直接改编辑器里的对象，一次调用就可能移动或删除受版本控制的资产。开始前先保存并提交（或搁置），做完先看差异再提交。
4. 本机不等于安全。服务只监听本机地址，能挡住浏览器网页的访问，但本机上同一用户的其他程序都能连上这个端口，而且它没有身份认证。不要在共享或不可信的机器上开这个服务，也不要把端口开放到本机以外。

Epic 文档还提到，编辑器会在游戏线程上逐个执行工具调用。互相依赖、会改同一处内容的操作，要一个一个来，不要并发。

常见问题

Windows 上 SessionStart 钩子不运行？

插件的启动钩子是一个 bash 脚本。Windows 原生 PowerShell 里没有 bash，钩子就不会运行。装 Git for Windows（自带 Git Bash）或者在 WSL 里运行 Claude Code 就好了。钩子不运行也不影响 MCP 工具，只是少了开场那句“这是 Unreal 项目”的提示，Claude Code 不会默认按 UE 的习惯来回答。

/mcp 里看不到 unreal-mcp？

按顺序查：

1. 有没有在编辑器里运行 ModelContextProtocol.GenerateClientConfig ClaudeCode。插件本身不带 .mcp.json，只装插件是看不到 unreal-mcp 的；
2. Claude Code 是不是在 .mcp.json 所在的目录里启动的（启动器版在 .uproject 旁边，源码版在工作区根目录）；
3. 第一次打开时是不是选了“Continue without using this MCP server”。在终端运行 claude mcp reset-project-choices 清掉之前的选择，再重新打开 Claude Code，这次选 Use this MCP server；
4. 看得到但显示 ✘ failed、原因是 ECONNREFUSED，说明编辑器没开或者服务没启动。启动后在 /mcp 里点 Reconnect。

8000 端口被占用怎么办？

编辑器日志里出现 Failed to listen on port，说明别的程序占了 8000 端口。在控制台运行 ModelContextProtocol.StartServer 端口号 换一个端口，或者在 Editor Preferences 里改掉默认端口。改完一定要重新运行一次 ModelContextProtocol.GenerateClientConfig ClaudeCode，让 .mcp.json 里的地址跟着变，否则 Claude Code 还在连旧端口。

用第三方 API 能用这个插件吗？

能。插件安装只是从 GitHub 拉文件，我们全程只配了 AICodeWith 的 Key，没有出现登录提示，插件的技能和钩子都正常加载。Unreal MCP 服务跑在你自己的电脑上，Claude Code 直接连本机地址，和模型请求走哪个 API 地址是两回事。

编辑器关了，Claude Code 会报错吗？

不会影响启动。我们实测编辑器没开时，Claude Code 照常打开，只是 /mcp 里 unreal-mcp 显示连接失败，这时让它操作编辑器自然做不了。编辑器打开后在 /mcp 里 Reconnect 即可。

立即注册，用 Claude Code 操作你的 UE5 项目 →

资料来源

• EpicGames/unreal-engine-skills-for-claude-code-plugin（GitHub）
• Epic Games：Unreal MCP in Unreal Editor
• Claude Code：Discover and install plugins