配置 — Unreal Engine · AI Game Developer Wiki

本页列出 Unreal MCP 目前提供的所有设置项以及在哪里修改它们。大多数人只需要调整连接模式和 AI agent 设置；其余设置用于调优、自动化和 CI。

设置存放位置

Unreal MCP 没有用于编辑器连接的 Project Settings 页面。所有设置都在 AI Game Developer 窗口（Tools 菜单）中，并按项目保存在：

<YourProject>/Saved/Config/UnrealMcp/ai-game-developer-config.json

每个 Unreal 项目模板都会忽略版本控制中的 Saved/，因此该文件中的 token 默认不会进入你的代码仓库。

设置的读取顺序如下，优先级从高到低：

进程环境变量（例如由 unreal-mcp-cli open 或你的 shell 设置）。
项目根目录下的 .env 文件。
上面的配置文件。
内置默认值。

来自环境变量或 .env 的值会在该会话中覆盖配置文件，但永远不会写回文件。

AI Game Developer 窗口

区域	你可以做什么
标题栏	选择 Log Level（Trace、Debug、Info、Warning、Error、Exception、None），用 Open log file 打开项目的日志文件夹，查看插件 Version
连接	切换 Custom / Cloud；在 Cloud 模式下可 Authorize、Cancel 或 Revoke；在 Custom 模式下设置 Server URL；Connect / Disconnect / Stop；查看 Unreal、MCP 服务器和已连接 AI agent 的状态，以及 IPC bridge 端口
MCP 服务器（Custom 模式）	Start / Stop 本地 `gamedev-mcp-server`，选择 Transport（http 或 stdio）和 Authorization 模式（none、token、oauth），用 New 生成 token
AI agent	选择一个 agent，然后 Configure、Reconfigure 或 Remove 它的 MCP 条目；打开它的 Tutorial 或 Download / Docs；Generate skill files；为项目 key 执行 Regenerate key
扩展	查看已安装和可用的扩展，Refresh catalog、Install 或 Update，实时启用或禁用某个扩展，Compile (Live Coding)
页脚	Help / Talk（Discord）、Bug Report（GitHub）、GitHub Star，以及 Restart bridge

连接相关的详细信息见 Connecting AI clients，扩展相关内容见 Extensions。

MCP Tools 窗口：单个工具的可见性

打开 Tools，然后打开 MCP Tools。该窗口列出所有已注册的工具及其标题、所属类别和描述，每个工具都有一个 Visible 复选框，还会显示类似“27 / 27 tools visible”的摘要。

Visible 决定某个工具是否会在 tools/list 中列给 AI agent。隐藏你不需要的工具可以缩短 agent 的工具列表并节省 token。
这不是访问控制。隐藏的工具在被客户端按名称调用时仍会执行，而且 unreal-tool-list 会显示隐藏的工具（标记为 hidden），因此 agent 仍然能找到它们。
该选择会保存为 hiddenTools，在编辑器重启和扩展重新加载后依然有效。

如果想让某个工具完全不被提供，请使用下面的 UNREAL_MCP_TOOLS 白名单。

其他窗口

Tools 菜单中还有 MCP Prompts 和 MCP Resources 窗口。在当前版本中，它们只显示空状态提示；插件或扩展注册的 prompts 和 resources 对 AI 客户端仍然可用。Serialization Check 窗口可将选中的 actor 或对象序列化为 JSON，以便你查看工具所看到的内容。

环境变量

插件会从进程环境变量或项目的 .env 文件中读取以下 UNREAL_MCP_* 变量：

变量	用途
`UNREAL_MCP_CONNECTION_MODE`	`Cloud`（默认）或 `Custom`
`UNREAL_MCP_HOST`	Custom 模式下的服务器 URL，例如 `http://localhost:<port>`
`UNREAL_MCP_CLOUD_URL`	Cloud 基础 URL；默认为 ai-game.dev
`UNREAL_MCP_TOKEN`	认证 token。属于机密信息：切勿提交
`UNREAL_MCP_AUTH_OPTION`	Custom 模式的认证方式：`none`、`token` 或 `oauth`（旧值 `required` 会被当作 `token`）
`UNREAL_MCP_KEEP_CONNECTED`	启动时自动恢复连接（默认 true）
`UNREAL_MCP_TOOLS`	要提供的工具白名单；为空表示不进行过滤
`UNREAL_MCP_START_SERVER`	`true`：由编辑器自己启动本地服务器（仅限 Custom 模式的 http），并在退出时停止它
`UNREAL_MCP_TRANSPORT`	`http` 或 `stdio`
`UNREAL_MCP_LOG_LEVEL`	日志详细程度
`UNREAL_MCP_TOOL_TIMEOUT`	单次工具调用的最长时间，单位为毫秒；默认 `300000`（5 分钟）
`UNREAL_MCP_BRIDGE_PATH`	bridge 二进制文件的路径；这是开发者覆盖项，优先级高于内置的版本
`UNREAL_MCP_SERVER_PATH`	本地 `gamedev-mcp-server` 的路径；由 `unreal-mcp-cli` 读取，会跳过其服务器下载

提示： 如果耗时较长的 python-execute 脚本或大型资产导入出现超时，请调高 UNREAL_MCP_TOOL_TIMEOUT。在编辑器开始执行之前就超时的工具调用会被跳过，而不会稍后再运行。

用 CLI 写入 .env

unreal-mcp-cli configure 会将这些值写入 <project>/.env，并把 .env 添加到项目的 .gitignore 中：

unreal-mcp-cli configure --path ./YourProject --mode Custom --host http://localhost:23456 --start-server

Unreal 项目模板默认不带 .gitignore，因此该命令会在需要时创建一个。传入 --no-gitignore 可保持原样。所有参数见 CLI 参考。

警告： 切勿提交 .env。它可能包含 UNREAL_MCP_TOKEN。

磁盘上的凭据与密钥

文件	内容
`~/.ai-game-dev/credentials.json`	整台机器范围的 ai-game.dev 登录信息，与应用、插件和各 CLI 共享
`~/.ai-game-dev/project-keys.json`	缓存的 project key，用于 Cloud MCP 配置
`<project>/Saved/Config/UnrealMcp/ai-game-developer-config.json`	该插件的按项目设置
`<project>/.env`	可选的覆盖项，永远不会被提交

端口

本地 MCP 服务器使用一个固定的按项目端口，范围在 20000 到 29999 之间，由项目路径计算得出。CLI 会算出相同的数字，因此无需任何配置。
插件与其 bridge 通过 30000 到 39999 之间的回环端口通信（发生冲突时使用下一个空闲端口）。窗口中将其显示为 "IPC bridge port"。

你永远不需要将这些端口对外开放到网络；两者都是本地的。

设置存放位置#

AI Game Developer 窗口#

MCP Tools 窗口：单个工具的可见性#

其他窗口#

环境变量#

用 CLI 写入 .env#

磁盘上的凭据与密钥#

端口#