Unreal MCP

Unreal MCP在虚幻编辑器进程中嵌入了一个MCP服务器，任何兼容MCP的AI代理（如Claude Code、Cursor或MCP Inspector），均可通过本地HTTP连接驱动编辑器。 该插件以工具形式开放引擎功能，例如生成Actor、配置光照、创建材质实例、检查Slate控件、运行自动化测试，AI代理可以代表用户调用这些工具，用户可以使用自定义工具轻松扩展这些功能。

什么是模型上下文协议？

模型上下文协议（MCP）是一种开放标准，发布于modelcontextprotocol.io。 该协议定义了AI客户端如何通过一小部分JSON-RPC消息类型（如initialize、tools/list、tools/call等）与MCP服务器通信。 服务器提供三种原语：

• 工具是客户端可以调用的指定函数，附带类型化参数及返回值。

• 资源是客户端可以通过统一资源标识符（URI）获取的只读数据。

• 提示是可重复使用的提示模板。

Unreal MCP是一个MCP服务器：公布由虚幻引擎功能支持的工具，并接受任何遵循该协议的客户端连接。

该插件在编辑器进程中运行。 默认情况下，服务器只接受来自同一台机器的连接，没有身份验证层，并且不适用于远程使用。 具体的绑定行为参见限制与已知问题部分。

MCP服务器的核心功能之一是通过在游戏线程上串行执行工具调用，将外部请求与虚幻引擎游戏线程同步，这意味着客户端不应发出重叠的工具调用。

设置

设置遵循以下主要步骤：

• 启用Unreal MCP和All Toolsets插件。

• 配置自动开启。

• 生成客户端配置文件。

• 从项目根目录启动AI代理。

• [可选]使用集成的Terminal插件运行AI代理，将整个工作流程保持在编辑器内部。

启用插件

打开编辑（Edit） > 插件（Plugins），搜索Unreal MCP，勾选已启用（Enabled）复选框。 搜索All Toolsets插件，勾选已启用（Enabled）复选框。 这些插件依赖Toolset Registry插件，该插件会自动启用。 弹出提示后重启编辑器。

配置自动开启

打开编辑（Edit） > 编辑器偏好设置（Editor Preferences），滚动至通用（General）类别，选择模型上下文协议（Model Context Protocol）。 该面板会显示自动开启服务器（Auto Start Server）设置。 启用后，每次启动编辑器，都将自动开启MCP服务器，并绑定到http://127.0.0.1:8000/mcp。

该面板还会显示监听端口（默认为8000）和URL路径（默认为/mcp），适用于默认值与其他本地服务发生冲突的环境。 serverInfo.name中公布的服务器名称始终为unreal-mcp。

要想按需启动服务器，请关闭自动开启服务器，并在编辑器控制台中输入ModelContextProtocol.StartServer。 该命令还支持一个可选端口：ModelContextProtocol.StartServer 8000。

生成客户端配置

每个AI代理都希望其服务器列表以特定文件格式，存放在项目树中的特定位置。 插件会直接将其写入该文件。 在编辑器控制台（默认按反引号键打开）中输入：

ModelContextProtocol.GenerateClientConfig ClaudeCode

该命令会将.mcp.json写入项目根目录，其中包含指向正在运行的服务器的正确条目。 支持的客户端名称包括ClaudeCode、Cursor、VSCode、Gemini、Codex、All。 同时配置多个代理时，请使用All：

ModelContextProtocol.GenerateClientConfig All

为Claude Code生成的.mcp.json文件如下所示：

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

JSON格式的配置（Claude Code、Cursor、VS Code、Gemini）会与现有条目合并，因此重复运行该命令是安全的。 Codex CLI使用的TOML配置只写一次：该命令拒绝覆盖现有文件，过时的配置必须手动删除。

通过您选择的AI代理建立连接

如需连接，请从生成配置文件的项目或工作区根目录启动您首选的AI代理CLI或应用程序。 如需了解具体连接步骤及高级设置，请参阅所选AI客户端的文档。

如果连接遇到问题，可尝试以下操作：

如果AI代理CLI或应用未找到Unreal MCP，请确认是否从生成配置文件的项目或工作区根目录启动AI代理CLI或应用。

尝试在编辑器启动后，启动您所选择的AI代理，否则可能需要重新连接MCP。 具体操作如下：

1. 启动虚幻编辑器，确保MCP已启动。

2. 在工作区根目录中启动AI代理（从编辑器监听MCP的代理）。

可选：使用Terminal插件执行一次性操作

Terminal插件在编辑器中嵌入了一个功能齐全的终端面板，支持在面板打开时自动运行shell命令。 与Unreal MCP配合使用，可在一个编辑器窗口中完成整个工作流程。

要设置Terminal插件：

1. 打开编辑（Edit） > 插件（Plugins），搜索Terminal。 请重启编辑器以便让插件生效。

2. 打开编辑器偏好设置（Editor Preferences） > 通用（General） > Terminal。

在Terminal编辑器偏好设置中，按照以下顺序将条目添加到启动命令列表中：

1. 设置终端类型，以便AI代理CLI检测到可用的终端。

   警告：若不设置，claude及类似CLI将回退至降级模式，并可能输出原始转义序列，而非格式化输出。

   1. Windows(cmd.exe)：set TERM=xterm-256color。

   2. Unix shell（bash, zsh）：export TERM=xterm-256color。

2. 改为GenerateClientConfig写入.mcp.json的目录（已安装版本中为项目根目录，源码版本中为工作区根目录）。

   1. Windows：cd /d "<path>"。

   2. Unix：cd "<path>"。

3. 设置要使用的AI代理CLI。 在本示例中，设置claude

显式cd是确保该方法具有可移植性的关键：Terminal面板会在FPaths::RootDir()中启动新会话，该路径在源码版本中为工作区根目录，在已安装版本中为引擎安装目录，因此工作目录与.mcp.json所在的目录可能不一致。

快速入门

服务器运行且AI代理已连接后，即可开始与虚幻引擎交互。

首先，尝试问一个简单的问题，确认AI代理已连接并能从编辑器接收上下文，例如：

• “我选择了哪些Actor？”

• "虚幻引擎能做什么？"

接下来就可以自由发挥！ 结果可能因使用的AI代理而异。

工具集和Toolset Registry

该插件通过查询Toolset Registry发现工具。Toolset Registry是由同名兄弟插件提供的一个虚幻引擎子系统。

工具集是一个派生自UToolsetDefinition（Python中为unreal.ToolsetDefinition）的类，公开了一个或多个标记为工具调用的函数。

Toolset Registry会在启动时收集每个工具集类，Unreal MCP会将每个工具调用封装为MCP工具，封装后的工具可供每个连接的MCP客户端使用。 引擎中的其他AI界面会使用该注册表，因此为MCP编写的工具集无需修改，即可用于这些界面。

编写MCP工具

为运行中的服务器添加工具有两种方法。 第一种是推荐路径，几乎适用于所有场景。 第二种适用于反射驱动发现不适用的高级场景。

使用Toolset Registry的推荐路径

工具集是一个派生自unreal.ToolsetDefinition（Python）或UToolsetDefinition（C++）的类，可将相关工具归类分组。 两种语言都很好；选择适合工作的即可。 Toolset Registry插件自带的大多数工具集，包括SceneTools、ActorTools、MaterialInstanceTools和ObjectTools，都是用Python编写的。

使用Claude Code的用户可通过unreal-mcp Claude Code插件中的create-toolset技能，构建Python或C++语言的新工具集。 以下规范在构建完成后仍然适用；该技能仅删除了样板代码。

使用Python编写

Python工具集以.py模块的形式存放于任何插件的Content/Python/目录中。 注册表会在启动时发现它们。 随附的ActorTools（当前位于Engine/Plugins/Experimental/ToolsetRegistry/Content/Python/toolset_registry/toolsets/core/actor.py）非常简洁，可以逐步讲解：

import unreal
import toolset_registry
from toolset_registry.toolsets.core.utils import require_editable


@unreal.uclass()
class ActorTools(unreal.ToolsetDefinition):
    """Provides tools for inspecting and modifying actors, including
    their transforms, labels, parent-child relationships, and components."""

以下规范适用：

• @unreal.uclass()装饰器将类公开给虚幻引擎反射。 该类继承自unreal.ToolsetDefinition。

• 类文档字符串用于描述工具集本身，并作为工具集的分组说明显示。

• 每个工具函数都包含@toolset_registry.tool_call装饰器，并声明为@staticmethod。 不公布没有@toolset_registry.tool_call的函数。

• 参数和返回类型提示（unreal.Actor、str、bool、list[str]、dataclasses等）驱动工具公布的JSON Schema。

• 函数文档字符串使用Google风格，包含Args:和Returns:块。 描述文本和每个参数的描述会反映到工具的模式中，编写时应像对待其他API的公共表面一样谨慎。

使用C++编写

C++工具集在不同的语法下遵循相同的模式。 派生自UToolsetDefinition，将类标记为UCLASS(BlueprintType, Hidden)，并公开静态UFUNCTION(meta = (AICallable))方法。 函数及每个参数的文档注释会以与Python文档字符串相同的方式反映到模式中。

GASToolsets插件中的UAttributeSetToolset就是一个完整示例（Engine/Plugins/Experimental/Toolsets/GASToolsets/Source/GASToolsets/Private/AttributeSetToolset.h）。 它公开了两个AICallable函数，返回类型为普通USTRUCT，且无异步行为。 请注意，GASToolsets是一个实验性引擎插件，默认禁用；首次启用时，会弹出实验性功能警告提示。

在以下情况下，请使用C++：

• 工具需要未向Python公开的引擎功能。

• 工具签名使用USTRUCT或其他反射类型，这些类型无法通过Python类型提示清晰表达。

• 工具的调用足够频繁，以至于Python到引擎的边界成本产生影响。

编写后

在编辑器控制台中执行ModelContextProtocol.RefreshTools，强制插件重新轮询注册表。 对于C++工具，Live Coding会检测现有函数体的更改；添加新的UFUNCTION需要完全重启编辑器。

遵循以下准则生成的工具能在AI客户端可靠调用，无论使用何种语言：

• 函数应保持精简和专注。 一个工具，一项职责。

• 优先使用描述性的函数名称和结构化的返回类型，而非自由格式的字符串。 结构化类型序列化为包含字段级类型与描述的JSON Schema；自由格式的字符串不含模式，强制客户端自行解析。

• 如果不想公布工具集中的某个函数，请省略@toolset_registry.tool_call（Python）或添加 meta = (AIIgnore)（C++）。

直接注册

当反射驱动发现无法满足需求时（在运行时确定模式的工具、动态出现和消失的工具，或者由类型系统外的数据支持的工具），直接实现IModelContextProtocolTool并注册实现：

TSharedRef<IModelContextProtocolTool> Tool = MakeShared<FMyDynamicTool>();
IModelContextProtocolModule::GetChecked().AddTool(Tool);

当工具的生命周期结束时，调用者负责注销该工具。 接口方法在游戏线程上调用（HTTP服务器通过核心计时器Tick），与Toolset Registry发现的工具相同。

配置参考

编辑器偏好设置：模型上下文协议

控制台命令

命令行标记

控制台变量

调试

启动时输出日志。 启用自动开启后，服务器会在编辑器初始化期间将其绑定地址、端口和URL路径记录到输出日志中。 绑定失败（端口已被占用、缺少依赖插件等）会在此处显示。 如果服务器疑似未运行，应先检查此处。

LogModelContextProtocol日志类别。 所有插件输出都通过LogModelContextProtocol传输。 如需更详细的日志，请在编辑器控制台中开启LogModelContextProtocol Verbose。

MCP Inspector。 MCP Inspector是所有MCP服务器的官方调试客户端，以npx命令形式发布。 当工具无法显示、返回错误形状或报告协议级错误时，将Inspector指向正在运行的服务器：它会列出所有已公布的工具及其声明的模式，并提供一个表单式调用界面，绕过任何AI代理对请求的解释。

可用npx @modelcontextprotocol/inspector启动Inspector。

打开Inspector窗口后，通过Streamable HTTP传输模式将其指向http://127.0.0.1:8000/mcp。

ModelContextProtocol.RefreshTools。 插件在启动时缓存工具集列表。 在编写新的工具集、热重载已修改的函数体或激活提供工具集的Game Feature插件后，运行此命令以强制重新轮询。 在对工具集方法进行Live Coding处理后，已连接的客户端可能仍保留旧的工具模式；运行RefreshTools并重新连接客户端。

编辑器和运行时可用性

插件分布在三个模块中。 ModelContextProtocol和ModelContextProtocolEngine是运行时模块：它们拥有服务器、协议实现、设置以及StartServer、StopServer、RefreshTools和GenerateClientConfig控制台命令。 ModelContextProtocolEditor仅适用于编辑器，仅负责自动启动的钩子，以及将Toolset Registry发现的工具集适配到MCP工具中。

因此，服务器与编辑器并未严格绑定。 已烘焙和发布的游戏版本可以通过在启动时调用IModelContextProtocolModule::StartServer()来托管MCP服务器。

工具搜索

默认情况下，插件以工具搜索模式运行（bEnableToolSearch = true）。 在该模式下，tools/list会返回三个发现元工具，而非所有已公布的工具：

代理按需执行此发现路径，即使注册表公开数百个工具，tools/list响应也很小。 设为false将恢复为主动公布所有工具的模式，但会导致初始模式负载显著增大。 工具开发者不应依赖工具的主动公布；默认情况下，连接代理将看到工具搜索路径。

工具搜索元工具本身属于编辑器专用适配器的一部分。 直接通过IModelContextProtocolModule::AddTool()注册工具的烘焙版本主机将主动公布工具，无论bEnableToolSearch如何设置。

局限性和已知问题

• 仅支持HTTP和服务器发送事件。 不支持stdio和WebSocket传输。

• 默认仅支持环回。 HTTP监听器将按[HTTPServer.Listeners] DefaultBindAddress（默认localhost）绑定，服务器拒绝非环回Origin头。 没有身份验证层；该插件不宜暴露在本地计算机之外。

• 任何发布工具集均不会公布MCP资源和提示。

• Toolset Registry适配器仅适用于编辑器。 已烘焙和发布的版本可以托管MCP服务器（参见编辑器和运行时可用性），但通过注册表发布的工具不会自动被发现，必须通过IModelContextProtocolModule::AddTool()显式注册。

• Live Coding不会传播新的UFUNCTION声明。 添加工具需要重新启动编辑器。

另请参阅

• 模型上下文协议规范

• MCP Inspector