設定 — Unreal Engine · AI Game Developer Wiki

本頁列出 Unreal MCP 目前所有的設定項目，以及各自該到哪裡修改。大多數人只會調整連線模式與 AI 代理設定，其餘部分則用於調校、自動化與 CI。

設定存放位置

Unreal MCP 沒有針對編輯器連線的 Project Settings 頁面。所有設定都在 AI Game Developer 視窗（Tools 選單）中，並依專案儲存於：

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

Saved/ 在所有 Unreal 專案範本中都會被版本控制忽略，因此這個檔案裡的權杖預設不會進到你的儲存庫。

設定的讀取順序如下，優先權由高到低：

行程環境變數（例如由 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 代理的狀態，以及 IPC bridge 連接埠
MCP 伺服器（Custom 模式）	以 Start / Stop 控制本機的 `gamedev-mcp-server`，選擇 Transport（http 或 stdio）與 Authorization 模式（none、token、oauth），並可用 New 產生權杖
AI 代理	選擇一個代理後，Configure、Reconfigure 或 Remove 它的 MCP 項目；開啟它的 Tutorial 或 Download / Docs；Generate skill files；為專案金鑰執行 Regenerate key
擴充功能	查看已安裝與可用的擴充功能，Refresh catalog、Install 或 Update，即時啟用或停用擴充功能，Compile (Live Coding)
頁尾	Help / Talk（Discord）、Bug Report（GitHub）、GitHub Star，以及 Restart bridge

連線細節請見連接 AI 用戶端，擴充功能請見擴充功能。

MCP Tools 視窗：個別工具的可見性

依序開啟 Tools 與 MCP Tools。視窗會列出所有已註冊的工具，包含標題、分類與說明，每個工具都有一個 Visible 核取方塊，以及像「27 / 27 tools visible」這樣的摘要。

Visible 決定工具是否會出現在提供給 AI 代理的 tools/list 中。隱藏用不到的工具可讓代理的工具清單保持精簡，節省權杖。
這不是存取控制。用戶端以名稱呼叫時，隱藏的工具仍會執行，而 unreal-tool-list 會顯示隱藏的工具（標示為 hidden），讓代理仍能找到它們。
此選擇會儲存為 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`	雲端基底 URL；預設為 ai-game.dev
`UNREAL_MCP_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`	快取的專案金鑰，用於 Cloud MCP 設定
`<project>/Saved/Config/UnrealMcp/ai-game-developer-config.json`	外掛的個別專案設定
`<project>/.env`	選用的覆寫設定，絕不提交

連接埠

本機 MCP 伺服器會使用 20000 到 29999 之間、依專案固定的一個連接埠，由專案路徑計算得出。CLI 會算出相同的數字，因此不需任何設定。
外掛與其橋接程式透過 30000 到 39999 之間的迴路連接埠通訊（發生衝突時使用下一個可用連接埠）。視窗會將其顯示為「IPC bridge port」。

你完全不需要對網路開放這些連接埠；兩者都是本機的。

設定存放位置#

AI Game Developer 視窗#

MCP Tools 視窗：個別工具的可見性#

其他視窗#

環境變數#

使用 CLI 寫入 .env#

磁碟上的認證與金鑰#

連接埠#