本頁面由英文機器翻譯而成。閱讀英文原文。

疑難排解

修正常見的 Unreal MCP 問題：外掛未載入、缺少 bridge、連線卡住、AI agent 沒有 Unreal 工具、建置過舊與工具錯誤。

更新於 2026年11月4日 以 Markdown 檢視

本頁列出使用 Unreal MCP 時最常遇到的問題，以及對應的解決方法。請先做快速檢查，再跳到相符的段落。

快速檢查

  1. 外掛載入了嗎？ 編輯器啟動後，Output Log 應該會出現 [Unreal-MCP] plugin loaded。
  2. 視窗顯示什麼？ 開啟 Tools、AI Game Developer，查看狀態列（Connected、Connecting、Reconnecting、Disconnected 或 No MCP bridge）。
  3. CLI 看到什麼？ 執行 unreal-mcp-cli status --path ./YourProject。
  4. 查看日誌。 使用視窗中的 Open log file，在 Output Log 中以 LogUnrealMcp 類別篩選，或請 agent 執行 console | where Verbosity == "Error"。

外掛沒有載入

如果沒有 [Unreal-MCP] plugin loaded 這一行，代表編輯器模組啟動失敗。

  • 在 Output Log 中尋找外掛的啟動錯誤，或損壞的 .uplugin。
  • 確認專案是 C++ project，且編譯器工具鏈可正常運作。請參閱 Installation。
  • 如果 Unreal 顯示模組遺失或外掛不相容，讓它重新建置，或使用 unreal-mcp-cli open ./YourProject 開啟專案，這會先建置原生模組並略過那些提示。

更新後沒有生效

當外掛原始碼變更、但舊的 Intermediate/ 資料夾仍留存時，Unreal 的增量建置可能會沿用舊的外掛程式碼。

  • 使用 unreal-mcp-cli update ./YourProject 更新，它預設會清除建置快取。
  • 手動複製之後：關閉編輯器，刪除 Plugins/UnrealMCP/Intermediate/ 以及 Plugins/UnrealMCP/Binaries/ 中的 C++ 檔案（保留 Binaries/ThirdParty/），然後重新開啟。

「No MCP bridge」或 bridge 不斷重新啟動

外掛需要它的 bridge 程序 unreal-mcp-bridge。視窗會顯示 bridge 狀態與重新啟動次數。

  • 如果日誌顯示 no sidecar binary resolved for rid <rid>，表示找不到 bridge。
    • App 或 CLI 安裝： bridge 已一併打包。使用 unreal-mcp-cli install-plugin ./YourProject（或從 app）重新安裝；該套件可能不包含你的平台。
    • 原始碼 checkout： 使用 unreal-mcp-cli bootstrap-local ./YourProject 建置一個，或設定 UNREAL_MCP_BRIDGE_PATH。
  • 修正原因後，點擊視窗底部的 Restart bridge。

卡在「Connecting」或「Reconnecting」

  • Cloud 模式： 確認你已登入。若視窗顯示「Sign in required」，表示已儲存的登入狀態已過期；點擊 Authorize 並核准新的驗證碼。
  • 確認這台機器能連上 ai-game.dev（代理伺服器或防火牆規則）。
  • Custom 模式： 確認本機伺服器正在執行（MCP server 卡片中的 Start，或 --start-server），且 Server URL 指向它。
  • 使用 Disconnect 再按 Connect，或按 Restart bridge。

本機伺服器顯示「No connected clients」

如果本機的 gamedev-mcp-server 記錄 No connected clients. Retrying，之後又以 HTTP 500 回應，表示編輯器仍處於 Cloud 模式，連到 ai-game.dev 而不是你的本機伺服器。請在視窗中切換為 Custom、設定 UNREAL_MCP_CONNECTION_MODE=Custom，或對 unreal-mcp-cli open 傳入 --connection-mode Custom（或 --host）。

AI agent 沒有 Unreal 工具

  • 檢查 agent 的設定：執行 unreal-mcp-cli setup-mcp <agent> --path ./YourProject --dry-run 並比對，或在 AI agent 區塊點擊 Configure（或 Reconfigure）。
  • 設定變更後，重新啟動或重新載入 agent。許多用戶端只在啟動時讀取 MCP 設定。
  • Claude Code 會從你啟動它的資料夾讀取 .mcp.json；請在專案資料夾中啟動。
  • 如果你在還沒開啟過編輯器之前就用 setup-mcp 設定，設定可能指向 localhost 而非雲端。先開啟專案一次，再執行 setup-mcp，或傳入 --url。
  • 查看 Connection 區塊中的 AI agents 列。若你的 agent 沒有列出，表示它沒有連到與編輯器相同的伺服器。
  • 如果你在 MCP Tools 視窗中隱藏了工具，或設定了 UNREAL_MCP_TOOLS，agent 看到的工具會比較少。

agent 連到錯誤的編輯器

同一個帳號有多個編輯器時，請使用專案釘選的 URL（/mcp/p/<pin>），setup-mcp 預設就會寫入這個。重新執行 setup-mcp 時不要加 --no-pin。請參閱 Connecting AI clients。

agent 出現 401 錯誤

  • 在 Cloud 模式下，只有 URL 的設定需要由 agent 自行登入。你可以讓它執行自己的 OAuth 登入流程，或是在這台機器上登入（unreal-mcp-cli login）後再執行一次 setup-mcp，讓設定帶有 project key。
  • 如果 project key 已被撤銷，請在編輯器中使用 Regenerate key，或執行 setup-mcp --regenerate-key。
  • 在 Custom 模式搭配 token 驗證時，設定必須帶有與編輯器相同的 token。產生新 token 後，請使用 Reconfigure。

工具呼叫逾時

單次工具呼叫預設最多可執行 5 分鐘。若是長時間的 Python 腳本或大型匯入，請調高 UNREAL_MCP_TOOL_TIMEOUT（毫秒）。python-execute 另外有自己的 timeout（預設 30 秒），可由 agent 在每次呼叫時設定。

截圖工具傳回錯誤

像素擷取需要有 GPU 支援的編輯器。在 -nullrhi 之下，截圖工具會傳回結構化錯誤。unreal-mcp-cli exec 與 open --headless 啟動的編輯器會進行離屏算繪，因此在那裡截圖仍可正常運作。

Python 工具失敗

python-execute 使用 Unreal 的 Python Editor Script Plugin，而 Unreal MCP 會啟用該外掛。如果 Python 無法使用，請到 Edit, Plugins 確認該外掛已啟用。錯誤訊息會指向 snippet.py 的行號，那是 agent 送出的程式碼。

擴充功能沒有顯示

  • 擴充功能需要 Unreal Engine 5.7 以上版本，以及 Unreal MCP 0.26.0 以上版本。
  • 安裝後，擴充功能必須經過編譯：重新開啟編輯器、使用 --build，或在 Extensions 區段使用 Compile (Live Coding)。
  • 確認擴充功能已在 Extensions 區段中啟用。

還是卡住了嗎？

  • 請參閱 FAQ 與一般 FAQ。
  • 使用視窗中的 Help / Talk 到 Discord 詢問，或用 Bug Report 開一個 GitHub issue。請附上 Unreal 版本、你的作業系統、視窗的狀態列，以及相關的日誌行（切勿附上你的 token）。