# Unity MCP — AI Game Developer Wiki

Unity MCP 能將 Claude Code、Cursor、Copilot 等 AI 代理連接到 Unity 編輯器。從這裡開始了解安裝、設定、工具、擴充功能與 CLI。

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

Unity MCP 是 AI Game Developer 的 Unity 外掛。它把 AI 放進 Unity 編輯器：Claude Code、Cursor、GitHub Copilot、Codex 或 Gemini 等代理可以讀取並修改你的場景、GameObject、元件、預製件與資源，撰寫 C# 腳本、執行 C# 片段、執行你的 EditMode 與 PlayMode 測試、讀取 Console，並截取可供它檢視的螢幕畫面。本 wiki 說明如何安裝此外掛、連接 AI 用戶端，以及日常使用方式。

## Unity MCP 是什麼

Unity MCP 是一個 Unity 套件 `com.ivanmurzak.unity.mcp`，在 Package Manager 中顯示為 **AI Game Developer — MCP**。它在 Unity 編輯器內執行（若你選擇的話，也可在你的建置遊戲內執行）。它透過 Model Context Protocol（MCP）對外提供一組工具，這是 AI 用戶端用來呼叫外部工具的開放標準。與你對話的代理會看到這些工具，並呼叫它們來完成你要求的工作。

此外掛以 Apache-2.0 授權開放原始碼，位於 [Unity-MCP 儲存庫](https://github.com/IvanMurzak/Unity-MCP)。它與 Unreal MCP、Godot MCP 共用 MCP 與反射程式庫，因此這三個引擎外掛的運作方式相同，並使用同一個 ai-game.dev 帳號。

自 1.0.0 版起，多數編輯器工作都透過 **RQL** 進行，這是一種查詢編輯器資料的查詢語言：`rql-query` 工具負責讀取、`rql-mutate` 工具負責修改，而 `rql-schema` 描述可用的內容。另有少量專門工具涵蓋螢幕畫面、腳本、測試與套件。請參閱 [工具與 RQL](https://ai-game.dev/zh-hant/docs/wiki/unity/tools-and-rql)。

## 各部分如何協同運作

| 組成部分 | 作用 |
| --- | --- |
| Unity MCP 外掛 | 在 Unity 編輯器內執行，提供 AI 工具並連線至 MCP 伺服器。 |
| MCP 伺服器 | 位於 ai-game.dev 的託管伺服器（Cloud 模式，預設），或是外掛為你下載並啟動的本機 `gamedev-mcp-server`（Custom 模式）。 |
| AI 用戶端 | Claude Code、Claude Desktop、Cursor、VS Code Copilot、Codex、Gemini、Rider 等。它會連線到同一個伺服器。 |
| `unity-mcp-cli` | npm 命令列工具，可安裝外掛、讓你登入、寫入 AI 用戶端設定、開啟 Unity，並從終端機呼叫工具。 |
| AI Game Dev 應用程式 | 桌面應用程式，會安裝外掛、開啟編輯器並為你執行 AI 代理。 |

在 **Cloud** 模式下，編輯器與你的 AI 用戶端都會連線到 `https://ai-game.dev/mcp`，你只需用 ai-game.dev 帳號登入一次。在 **Custom** 模式下，外掛會在你的電腦上執行本機 MCP 伺服器，因此一切都在你的電腦內進行。[設定](https://ai-game.dev/zh-hant/docs/wiki/unity/configuration) 說明這兩種模式。

## 需求快速一覽

- Unity **2022.3** 或更新版本，包括 Unity 6。
- 專案路徑**不得包含空格**（若路徑包含空格，外掛會在啟動時記錄錯誤）。
- 首次使用時需要網際網路：外掛會從 NuGet 下載其 .NET 相依項目，並在 Custom 模式下下載其 MCP 伺服器二進位檔。
- 支援 MCP 的 AI 用戶端，或 [AI Game Dev 應用程式](https://ai-game.dev/docs/app)。

## 快速開始

最簡單的方式是使用桌面應用程式：[下載它](https://ai-game.dev/zh-hant/download)、登入並開啟你的 Unity 專案。它會為你安裝外掛並完成連線。[應用程式 wiki](https://ai-game.dev/zh-hant/docs/wiki/app) 說明了這個流程。

如果你偏好使用終端機與自己的 AI 用戶端，以下命令可讓 Unity 專案連上代理：

```bash
npm install -g unity-mcp-cli
unity-mcp-cli install-plugin ./MyUnityProject
unity-mcp-cli login
unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli open ./MyUnityProject
```

接著向你的代理提出類似「以半徑 2 圍成一圈建立 3 個立方體」的要求。[入門指南](https://ai-game.dev/zh-hant/docs/wiki/unity/getting-started) 會逐步說明相同步驟並附上解釋。

## 本節頁面

- [安裝](https://ai-game.dev/zh-hant/docs/wiki/unity/installation)：安裝外掛的所有方式（應用程式、`unity-mcp-cli`、OpenUPM、`.unitypackage` 安裝程式）以及如何解除安裝。
- [入門指南](https://ai-game.dev/zh-hant/docs/wiki/unity/getting-started)：你的第一次連線與第一批提示。
- [連接 AI 用戶端](https://ai-game.dev/zh-hant/docs/wiki/unity/connecting-ai-clients)：Cloud 與本機端點、登入、固定 URL，以及各代理的設定工具。
- [設定](https://ai-game.dev/zh-hant/docs/wiki/unity/configuration)：AI Game Developer 視窗、連線模式、連接埠、設定檔、環境變數覆寫與建置。
- [工具與 RQL](https://ai-game.dev/zh-hant/docs/wiki/unity/tools-and-rql)：代理在編輯器中能做什麼。
- [自訂工具](https://ai-game.dev/zh-hant/docs/wiki/unity/custom-tools)：把你自己的 C# 方法變成 AI 工具、提示與技能，包括在執行中的遊戲裡。
- [擴充功能](https://ai-game.dev/zh-hant/docs/wiki/unity/extensions)：適用於 Animation、Cinemachine、Input System、Navigation、ProBuilder、Terrain、Tilemap、Timeline 等的選用套件。
- [unity-mcp-cli 參考](https://ai-game.dev/zh-hant/docs/wiki/unity/cli)：每個命令與旗標。
- [疑難排解](https://ai-game.dev/zh-hant/docs/wiki/unity/troubleshooting)：常見問題的修正方式。
- [常見問答](https://ai-game.dev/zh-hant/docs/wiki/unity/faq)：常見問題的簡短解答。

## 網站上的更多內容

- [Unity 工具目錄](https://ai-game.dev/docs/tools/unity) 與 [RQL 參考](https://ai-game.dev/docs/rql)。
- [Unity 擴充功能目錄](https://ai-game.dev/docs/extensions/unity)。
- [Unity 最佳實務](https://ai-game.dev/docs/best-practices/unity)：提示撰寫與專案設定。
- [MCP 端點](https://ai-game.dev/zh-hant/mcp-endpoint-info)，內含各支援用戶端的設定片段。
- [驗證](https://ai-game.dev/docs/auth)、[快速入門](https://ai-game.dev/zh-hant/docs/quickstart) 與 [Unity 引擎頁面](https://ai-game.dev/zh-hant/engines/unity)。
- 其他引擎：[Unreal MCP](https://ai-game.dev/zh-hant/docs/wiki/unreal) 與 [Godot MCP](https://ai-game.dev/zh-hant/docs/wiki/godot)。

- [**安裝** 透過桌面應用程式、unity-mcp-cli、OpenUPM 或 .unitypackage 安裝程式，在 Unity 專案中安裝 Unity MCP（AI Game Developer）。](https://ai-game.dev/zh-hant/docs/wiki/unity/installation)
- [**開始使用** 透過 Unity MCP 把你的第一個 AI 代理連接到 Unity 編輯器，檢查連線，並在 Claude Code、Cursor 或 Copilot 中試用第一批提示詞。](https://ai-game.dev/zh-hant/docs/wiki/unity/getting-started)
- [**連接 AI 用戶端** 透過 ai-game.dev 雲端端點或本機伺服器，將 Claude Code、Cursor、Copilot、Codex、Gemini 等 MCP 用戶端連接到 Unity MCP。](https://ai-game.dev/zh-hant/docs/wiki/unity/connecting-ai-clients)
- [**設定** 在 AI Game Developer 視窗中設定 Unity MCP：Cloud 與 Custom 模式、本機伺服器、連接埠、傳輸方式、授權、工具、覆寫與 CI。](https://ai-game.dev/zh-hant/docs/wiki/unity/configuration)
- [**工具與 RQL** AI 代理在 Unity 編輯器中透過 Unity MCP 能做什麼：RQL 查詢與變更、螢幕擷取、C# 腳本、測試、套件與效能分析。](https://ai-game.dev/zh-hant/docs/wiki/unity/tools-and-rql)
- [**自訂工具** 用 C# 與 AiTool 屬性撰寫你自己的 Unity MCP 工具、提示、資源與技能，在主執行緒上執行，並在建置後的遊戲中使用。](https://ai-game.dev/zh-hant/docs/wiki/unity/custom-tools)
- [**擴充功能** Unity MCP 擴充功能為 Animation、Cinemachine、Input System、Navigation、ProBuilder、Splines、Terrain、Tilemap、Timeline 與粒子系統加入 AI 支援。](https://ai-game.dev/zh-hant/docs/wiki/unity/extensions)
- [**unity-mcp-cli 參考** unity-mcp-cli 指令參考：安裝 Unity MCP、登入、寫入 AI agent 設定、以 headless 模式開啟 Unity，並從終端機執行工具與 C#。](https://ai-game.dev/zh-hant/docs/wiki/unity/cli)
- [**疑難排解** 解決常見的 Unity MCP 問題：AI 用戶端中沒有工具、登入與連線錯誤、伺服器下載失敗、NuGet DLL 錯誤，以及連接埠衝突。](https://ai-game.dev/zh-hant/docs/wiki/unity/troubleshooting)
- [**常見問題** Unity MCP 常見問題解答：支援的 Unity 版本與 AI 用戶端、Cloud 與本機模式、費用、隱私、組建、CI 與 RQL。](https://ai-game.dev/zh-hant/docs/wiki/unity/faq)

---

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

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