# Unreal MCP — AI Game Developer Wiki

Unreal MCP 將 Claude、Cursor、Copilot 等 AI 代理連接到 Unreal 編輯器。了解外掛、橋接程式、CLI 與應用程式如何彼此搭配運作。

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/unreal)。

Unreal MCP 是 AI Game Developer 的 Unreal Engine 外掛。它讓 Claude Code、Cursor、GitHub Copilot、Codex 或 Gemini 等 AI 代理直接在 Unreal 編輯器內工作：查詢與變更 actor、元件、資產與關卡，撰寫並編譯 Blueprint，編輯並編譯 C++，執行編輯器 Python，以及擷取可供它查看的截圖。你以自然語言描述需求，代理便透過 Model Context Protocol（MCP）呼叫編輯器的工具。

本 wiki 說明如何安裝外掛、連接你的 AI 用戶端，以及如何在 Unreal 編輯器中讓 AI 產出有用的結果。外掛目前為 **beta**；現行版本是 0.26.2。

## 各部件的組合方式

一套 Unreal MCP 環境由四個部分組成。了解這四個部分，能讓設定與疑難排解輕鬆許多。

- **Unreal MCP 外掛**（`UnrealMCP`）。這是一個 C++ 編輯器外掛，安裝在專案的 `Plugins/` 資料夾中。它會註冊各項 AI 工具，並在編輯器中加入 **AI Game Developer** 視窗。
- **橋接程式**（`unreal-mcp-bridge`）。Unreal 編輯器是以 C++ 撰寫，因此 .NET 的 MCP 主機會以小型輔助程序的形式，在編輯器旁執行。外掛會自動啟動它，並透過受權杖保護的本機連線與之溝通。封裝發行版已內含橋接程式，因此你不需要安裝 .NET。
- **MCP 伺服器**。橋接程式預設會連線到託管於 [ai-game.dev](https://ai-game.dev) 的伺服器（**Cloud** 模式）。你也可以改為在自己的機器上執行共用的本機伺服器 `gamedev-mcp-server`（**Custom** 模式）。
- **你的 AI 用戶端**。任何 MCP 用戶端都會連線到同一個伺服器，並透過它連到你的編輯器。

有兩項工具可協助你完成這項設定：

- **AI Game Dev** 桌面應用程式會替你將外掛安裝到 Unreal 專案中，並可開啟編輯器。不需要 Node.js。請參閱[應用程式 wiki](https://ai-game.dev/zh-hant/docs/wiki/app)。
- **`unreal-mcp-cli`**，一個發佈於 npm 的跨平台命令列工具。它會安裝並更新外掛、讓你登入、寫入 MCP 用戶端設定、開啟編輯器，並可從終端機或 CI 執行工具。

## AI 代理能做什麼

外掛內含 7 個工具家族、共 27 項工具。大多數編輯器資料都透過 **RQL** 處理，這是一套適用於整個編輯器的查詢語言，而不是每個操作各用一項工具：

- **RQL**（`rql-query`、`rql-mutate`、`rql-schema`）：尋找並變更 actor、元件、資產、關卡、DataTable、gameplay tag、Project Settings、Blueprint 圖表、Widget Blueprint 與 Level Sequence。
- **Blueprints**：建立、編輯並編譯 Blueprint，並提供代理可據以修正的結構化錯誤清單。
- **C++ 原始碼**：讀取、建立範本、編輯並編譯專案 C++（Live Coding 或 Unreal Build Tool）。
- **Python**：以完整的 `unreal` 編輯器 API 執行 Python。
- **截圖**：視埠、遊戲視角、攝影機與隔離 actor 的擷取畫面。
- **Console** 與**工具清單**輔助功能。

六個選用擴充功能分別新增 Control Rig、Enhanced Input、Gameplay Ability System、Landscape 與 Water、Niagara 以及 PCG 支援。你也可以從任何 Unreal 外掛註冊自己的工具。

## Wiki 頁面

| 頁面 | 你將找到的內容 |
| --- | --- |
| [安裝](https://ai-game.dev/zh-hant/docs/wiki/unreal/installation) | 系統需求，以及目前所有可用的安裝方式：應用程式、CLI 與手動安裝 |
| [開始使用](https://ai-game.dev/zh-hant/docs/wiki/unreal/getting-started) | 首次連線、第一批提示詞，以及確認一切運作正常 |
| [連接 AI 用戶端](https://ai-game.dev/zh-hant/docs/wiki/unreal/connecting-ai-clients) | Cloud 與 Custom 模式、裝置碼登入、專案金鑰，以及針對各代理執行 `setup-mcp` |
| [設定](https://ai-game.dev/zh-hant/docs/wiki/unreal/configuration) | AI Game Developer 視窗、MCP Tools 視窗、設定檔與 `UNREAL_MCP_*` 變數 |
| [工具](https://ai-game.dev/zh-hant/docs/wiki/unreal/tools) | 每一項內建工具，以及該如何提出需求 |
| [擴充功能](https://ai-game.dev/zh-hant/docs/wiki/unreal/extensions) | 六個選用擴充功能及其安裝方式 |
| [自訂工具](https://ai-game.dev/zh-hant/docs/wiki/unreal/custom-tools) | 從 C++ 新增你自己的工具、提示詞與資源，包括遊戲內（執行階段）工具 |
| [CLI 參考](https://ai-game.dev/zh-hant/docs/wiki/unreal/cli) | 每一個 `unreal-mcp-cli` 命令與旗標 |
| [疑難排解](https://ai-game.dev/zh-hant/docs/wiki/unreal/troubleshooting) | 連線、橋接程式、建置與工具問題的修正方式 |
| [常見問題](https://ai-game.dev/zh-hant/docs/wiki/unreal/faq) | 常見問題的簡短解答 |

## 接下來該看什麼

- 第一次來嗎？請先閱讀[安裝](https://ai-game.dev/zh-hant/docs/wiki/unreal/installation)，接著看[開始使用](https://ai-game.dev/zh-hant/docs/wiki/unreal/getting-started)。
- 想要精簡版嗎？[Unreal Engine 安裝頁面](https://ai-game.dev/zh-hant/engines/unreal)與[快速入門](https://ai-game.dev/zh-hant/docs/quickstart)涵蓋了重點。
- 想了解工具細節嗎？請瀏覽 [Unreal 工具目錄](https://ai-game.dev/docs/tools/unreal) 和 [Unreal 最佳實務](https://ai-game.dev/docs/best-practices/unreal)。
- 同時使用其他引擎嗎？請參閱 [Unity wiki](https://ai-game.dev/zh-hant/docs/wiki/unity) 和 [Godot wiki](https://ai-game.dev/zh-hant/docs/wiki/godot)。這三個外掛共用同一個伺服器、帳號與 AI 用戶端。

- [**安裝** 使用 AI Game Dev 應用程式或 unreal-mcp-cli，在 Unreal Engine 5.5+ 安裝 Unreal MCP 外掛。包含需求、更新、移除與 Fab 狀態。](https://ai-game.dev/zh-hant/docs/wiki/unreal/installation)
- [**開始使用** 第一次連線 Unreal MCP，登入 ai-game.dev，接上你的 AI 用戶端，並在 Unreal Editor 中送出第一批 AI 提示。](https://ai-game.dev/zh-hant/docs/wiki/unreal/getting-started)
- [**連接 AI 用戶端** 將 Claude Code、Cursor、Copilot、Codex、Gemini 等 MCP 用戶端，透過 ai-game.dev 雲端端點或本機伺服器連上 Unreal MCP。](https://ai-game.dev/zh-hant/docs/wiki/unreal/connecting-ai-clients)
- [**設定** 設定 Unreal MCP：AI Game Developer 視窗、MCP Tools 可見性、專案設定檔、.env 以及所有 UNREAL\_MCP\_\* 環境變數。](https://ai-game.dev/zh-hant/docs/wiki/unreal/configuration)
- [**工具** 27 個內建 Unreal MCP 工具：RQL、Blueprints、C++ 原始碼、Python、螢幕擷取與主控台，以及 Unreal 編輯器中 AI 的範例提示。](https://ai-game.dev/zh-hant/docs/wiki/unreal/tools)
- [**擴充功能** Control Rig、Enhanced Input、GAS、Landscape 與 Water、Niagara 及 PCG 適用的選用 Unreal MCP 擴充功能，說明各自新增什麼以及如何安裝。](https://ai-game.dev/zh-hant/docs/wiki/unreal/extensions)
- [**自訂工具** 從任何 C++ 外掛將你自己的 AI 工具、RQL 模組、提示與資源加入 Unreal MCP，並在執行中的遊戲裡公開遊戲玩法工具。](https://ai-game.dev/zh-hant/docs/wiki/unreal/custom-tools)
- [**CLI 參考** 完整的 unreal-mcp-cli 命令參考：安裝 Unreal MCP 外掛、登入、設定 AI 代理程式、開啟編輯器、執行工具與 Python。](https://ai-game.dev/zh-hant/docs/wiki/unreal/cli)
- [**疑難排解** 修正常見的 Unreal MCP 問題：外掛未載入、缺少 bridge、連線卡住、AI agent 沒有 Unreal 工具、建置過舊與工具錯誤。](https://ai-game.dev/zh-hant/docs/wiki/unreal/troubleshooting)
- [**常見問題** Unreal MCP 常見問題解答：支援的引擎版本、AI 用戶端、純 Blueprint 專案、Fab、離線使用、費用與打包後的遊戲。](https://ai-game.dev/zh-hant/docs/wiki/unreal/faq)

---

Source (HTML): https://ai-game.dev/zh-hant/docs/wiki/unreal

Machine-translated (zh-Hant) from the English page: https://ai-game.dev/docs/wiki/unreal