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

安裝

使用 AI Game Dev 應用程式或 unreal-mcp-cli，在 Unreal Engine 5.5+ 安裝 Unreal MCP 外掛。包含需求、更新、移除與 Fab 狀態。

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

本頁說明如何將 Unreal MCP（Unreal Engine 的 AI Game Developer 外掛）安裝到專案中。請選擇一種安裝方式，依照步驟操作，然後繼續閱讀開始使用。

需求

需求項目詳細資訊
Unreal Engine5.5 或更新版本。發行版已針對 5.5、5.6、5.7 與 5.8 驗證。
專案類型C++ Unreal 專案。此外掛包含會針對你的專案編譯的編輯器模組，因此專案必須能夠建置 C++。
C++ 工具鏈你的 Unreal Engine 版本在你的平台上所需的編譯器工具鏈（例如 Windows 上的 Visual Studio、macOS 上的 Xcode）。
作業系統Windows (x64)、macOS（Apple silicon 與 Intel）以及 Linux (x64)。發行版會為上述每個平台提供橋接程式組建。
Node.js僅限 unreal-mcp-cli：^20.19.0 或 >=22.12.0。桌面應用程式不需要。
.NET 9 SDK僅在從原始碼建置橋接器時需要。封裝安裝版會一併包含。

此外掛不會在外掛描述檔中鎖定確切的引擎版本，因此同一個外掛也能在較新的引擎版本上載入。

注意： 純 Blueprint 專案需要先有 C++ 模組，才能建置外掛。請在 Unreal Editor 中加入任何 C++ 類別（Tools、New C++ Class），將它轉為 C++ 專案，或使用 unreal-mcp-cli create-project 建立全新的 C++ 專案。

選項 1：AI Game Dev 桌面應用程式

桌面應用程式是最簡單的方式。它內含安裝邏輯，因此你不需要 Node.js、npm 或終端機。

  1. 從下載頁面安裝 AI Game Dev。應用程式安裝指南會逐步說明。
  2. 使用你的 ai-game.dev 帳戶登入。
  3. 選擇 Open folder…，然後選取你的 Unreal 專案資料夾（包含 .uproject 檔案的資料夾）。應用程式會將其辨識為 Unreal 專案。或者使用 Create new project 建立新專案；外掛隨後會自動安裝。
  4. 在側邊欄中點擊 Install Package。應用程式會安裝最新發行的 Unreal MCP 版本，並先驗證下載內容。如果已安裝的外掛版本較新，應用程式會保留它。
  5. 點擊 Open Editor，以你已登入的工作階段啟動 Unreal Editor，讓外掛能透過 ai-game.dev 連線，而不需要手動權杖。

在應用程式的 CLI 中，相同動作對應的命令是 /install-plugin 與 /open。應用程式也能安裝選用的擴充功能。詳細資訊請參閱專案與引擎。

選項 2：unreal-mcp-cli

unreal-mcp-cli 發佈於 npm，可在 Windows、macOS 與 Linux 上運作。它不需要複製儲存庫，也不需要自行執行建置步驟。

全域安裝 CLI：

npm install -g unreal-mcp-cli

或者不安裝，直接執行任何命令一次：

npx unreal-mcp-cli@latest status

接著安裝外掛、登入並開啟編輯器：

# 1. Install the UnrealMCP plugin into <project>/Plugins/UnrealMCP
unreal-mcp-cli install-plugin ./YourProject

# 2. Sign in to ai-game.dev once per machine (device-code flow in your browser)
unreal-mcp-cli login

# 3. Open the Unreal Editor for the project
unreal-mcp-cli open ./YourProject

這些命令的作用如下：

  • install-plugin 會下載與 CLI 版本相符的外掛原始碼（來自 GitHub release 的 unreal-mcp-plugin-source-<version>.zip），並在解壓縮前檢查其簽章。遭竄改或未簽署的下載會遭到拒絕。適用於你平台的橋接器會包含在該套件中。
  • login 會將你的認證儲存在整台機器的儲存區（~/.ai-game-dev/credentials.json），與應用程式及其他引擎 CLI 共用。
  • open 會從專案的 EngineAssociation 找到正確的引擎，必要時先建置原生編輯器模組，並在已知的 Unreal 啟動提示（例如「Missing Modules」）仍出現時自動關閉它們。

提示： 安裝或更新外掛前，請先關閉 Unreal Editor。Unreal 無法取代執行中的編輯器已載入的外掛。

選項 3：從原始碼手動安裝

手動安裝適用於貢獻者與外掛開發。

  1. 將 Unreal-MCP 儲存庫中的 UnrealMCP/ 資料夾複製到 <YourProject>/Plugins/UnrealMCP/。
  2. 原始碼簽出版本不會隨附橋接器。請使用 unreal-mcp-cli bootstrap-local ./YourProject 建置一個（需要 .NET 9 SDK），或將 UNREAL_MCP_BRIDGE_PATH 指向你建置的橋接器。
  3. 開啟專案。Unreal 會在首次啟動時編譯此外掛的模組。

若需進行即時開發，unreal-mcp-cli install-plugin --junction 會以連結資料夾的方式取代複製外掛資料夾（Windows）。

Fab / Epic Marketplace

Fab 上架計畫正在進行中，但尚未上線。在上架前，Fab 上沒有可供安裝的內容；請使用應用程式或 CLI。

檢查安裝

編輯器啟動時，Output Log 會印出：

[Unreal-MCP] plugin loaded

你也可以執行 unreal-mcp-cli status --path ./YourProject 來查看套件、專案、外掛與連線狀態。

接著外掛就會以 AI Game Developer 之名出現在編輯器的 Tools 選單下。請繼續閱讀開始使用。

更新外掛

  • 應用程式： 有較新的外掛版本時，側邊欄會顯示 Update Package。
  • CLI： 執行 unreal-mcp-cli update ./YourProject。版本變更時，它會刪除已安裝外掛的 Intermediate/ 資料夾及其編譯後的 C++ Binaries/，讓 Unreal 進行一次乾淨的重新建置，同時保留內建的 bridge。加上 --force 可重新安裝相同版本，加上 --no-clean 則保留建置快取。
  • 手動複製： 關閉編輯器，刪除 Plugins/UnrealMCP/Intermediate/ 與 C++ 的 Binaries/（保留 Binaries/ThirdParty/），然後重新開啟專案。

建置快取過舊是更新看起來沒有生效最常見的原因。請參閱疑難排解。

移除外掛

unreal-mcp-cli remove-plugin ./YourProject

或者在編輯器關閉的情況下刪除 <YourProject>/Plugins/UnrealMCP/。

讓外掛不進入打包後的遊戲

如果你只是要在編輯器中用 Unreal MCP 取得 AI 協助，請在你的專案的 .uproject 外掛項目中將它排除於打包建置之外：

{
  "Name": "UnrealMCP",
  "Enabled": true,
  "TargetDenyList": ["Game", "Client", "Server"]
}

如此一來，外掛在編輯器中仍保持啟用，但它的任何部分（包括 bridge）都不會被編譯或暫存到打包後的遊戲中。請勿將任何 UnrealMcp* 模組加入遊戲模組 Build.cs 的相依項目：直接相依會覆寫拒絕清單。若想在執行中的遊戲內使用 AI 工具，請參閱遊戲內工具。