文章目錄

Unity 的 AI Assistant 套件內建一個 MCP 伺服器,讓 Claude Code 這類 AI Agent 能直接在執行中的 Unity 編輯器建立場景、修改元件、進入 Play Mode,做完再截圖確認畫面。Unity 在 2026 年 11 月 6 日把這個 MCP 伺服器標成棄用,改由 Unity CLI 接手。Unity CLI 免費,也不需要訂閱 Unity AI。社群維護的 MCP for Unity 是另一個獨立的套件,不受這次棄用影響。
我在 Claude Code 裝好 Unity 的官方 Plugin 後,只用文字描述想要一隻會旋轉的橘貓,Claude Code 就在開著的 Unity 編輯器裡建立場景、用基本形狀拼出貓、寫好旋轉腳本,再進入 Play Mode 截圖,看過截圖確認畫面裡有貓才回報完成。編輯器全程開著,Claude Code 建立的物件會直接出現在 Hierarchy,我們也能隨時接手調整。
測試環境是 Windows 11、Unity 6000.6.9f1、Unity CLI 1.0.0、MCP for Unity 10.3.0,以及 Claude Code 2.1.309 搭配 Sonnet 模型。
選擇接法
不同情況適合的接法如下:
| 情況 | 處理方式 |
|---|---|
| Claude Code 已經接上 AI Assistant 套件的 MCP | 移除舊設定,改用 Unity CLI |
| Agent 能在終端機執行指令,例如 Claude Code | 用 unity command |
| 客戶端只能呼叫 MCP 工具,不能執行終端機指令 | 用 unity mcp |
| 專案還在 Unity 2021.3 或 2022.3 | Unity CLI 要 Unity 6.0 以上才能操作編輯器,因此改用 MCP for Unity |
三種接法最後都會連到 Unity 編輯器裡的一個套件,差別在於 Agent 送出操作時經過的程式:
移除 AI Assistant 套件的 MCP 設定
用過 AI Assistant 套件的 MCP 時,Claude Code 的 MCP 清單裡會有一個執行 relay_win.exe --mcp 的項目,Unity 文件的範例名稱是 unity-mcp。在專案資料夾執行 claude mcp list 就能找到這個項目,再依名稱移除:
1claude mcp remove --scope user unity-mcp
如果當初把設定加在專案範圍,就要在專案資料夾裡把 user 改成 local,寫在專案的 .mcp.json 時則改成 project。unity mcp configure 雖然有 --replace-legacy 參數,但對 Claude Code 只會印出上面這行移除指令,不會替我們移除。
如果要保留這個套件,繼續使用編輯器裡的 AI Assistant 視窗,就要把套件更新到 2.13 以上。舊版的套件會和 Unity CLI 互相衝突。
設定 Unity CLI
Unity CLI 的安裝與登入見〈Unity CLI 安裝教學〉。要操作的專案需要用 Unity 6.0 以上的編輯器開啟,並且放在 NTFS 格式的磁碟。如果專案放在 ReFS 格式的開發磁碟機(Dev Drive),Unity CLI 會連不上編輯器,症狀見「問題排除」。
安裝 Pipeline 套件
Unity CLI 會經由編輯器裡的 Pipeline 套件操作編輯器,既有的專案要先在終端機安裝這個套件:
1unity pipeline install --project-path C:\UnityProjects\CatCli
用 unity projects create 建立的專案已經內建這個套件,執行上面的指令時會回報 alreadyInstalled 為 true。
確認編輯器已經連上
套件安裝好後,用 unity open 開啟專案,等編輯器載入完成再執行 unity status。當狀態顯示 ready 時,就代表 Unity CLI 能操作這個編輯器。這時可以自己截一張遊戲畫面,確認 unity command 可以正常使用:
1unity status --project-path C:\UnityProjects\CatCli
2unity command capture game_view --output-path Screenshots/cat.png
截圖的相對路徑以專案資料夾為起點:

unity command 不加參數時會列出所有指令群組,例如 scene、gameobject、script 與 capture,加上群組名稱就會列出群組裡的指令與參數。
安裝 Unity Plugin
確認指令可以使用後,再安裝 Unity 的官方 Plugin,讓 Claude Code 知道如何組合這些指令:
1unity setup claude
執行 claude plugin list 看到 unity@claude-plugins-official 的狀態是 enabled 就完成了。Plugin 裡的 unity-cli skill 寫明,Agent 能執行終端機指令時要用 unity command,不要用 MCP 伺服器。
設定 unity mcp
客戶端不能執行終端機指令時,要改用 unity mcp。unity mcp 是 Unity CLI 內建的 MCP 伺服器,一樣經由 Pipeline 套件操作編輯器,安裝 Pipeline 套件與確認連線這兩步同樣要做。接著替 Claude Code 加上設定:
1unity mcp configure claude-code
這個指令會執行 claude mcp add,把名為 unity-editor-mcp 的伺服器加到使用者範圍,所有專案都看得到。設定完成後用 claude mcp get unity-editor-mcp 確認狀態是 Connected:

預設的 --tool-groups 參數會把同一個群組的指令合併成一個工具,因此工具數量從 199 個減為 44 個。同時開啟好幾個專案時,在 configure 加上 --project-path 就能指定要操作的專案。其他客戶端的名稱可以用 unity mcp configure --list 查詢。
如果 Claude Code 同時裝了 Unity Plugin,Agent 可能會照 skill 的指示改用 unity command。我測試時有一次就是這樣,之後禁止 Claude Code 執行終端機指令,Agent 才只用 MCP 工具。
設定 MCP for Unity
MCP for Unity 是 Coplay 維護的開源套件,支援 Unity 2021.3 以上,工具清單裡也有生成圖片與 3D 模型、操作 ProBuilder 這類 Unity CLI 沒有的工具。MCP for Unity 的 MCP 伺服器用 Python 寫成,安裝前要先裝好 Python 3.10 以上,以及 Python 的套件管理工具 uv。
安裝套件
在 Package Manager 按左上角的「+」,選「Install package from git URL」,輸入下面的網址再按「Install」:
1https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v10.3.0
網址最後的 #v10.3.0 會固定安裝這個版本,拿掉版本號時會安裝 main 分支的最新版。安裝完成後,清單裡會出現來源是 Git 的 MCP for Unity:

設定 Claude Code
套件安裝好後會自動開啟「MCP Setup」視窗,視窗會先檢查 Python、uv 與 Git 是否已經安裝:

按「Next」後,視窗會列出電腦上找到的 MCP 客戶端,並且預設全部勾選。如果只要接上 Claude Code,就取消勾選其他項目,再按「Configure Selected」:

MCP for Unity 會把 Claude Code 的設定寫在這個專案的範圍,其他專案不受影響。設定的連線網址是 http://127.0.0.1:8080/mcp。
啟動伺服器
設定完成時伺服器還沒有啟動,因此 Claude Code 會連不上,claude mcp list 會顯示 UnityMCP 連線被拒(ECONNREFUSED)。從選單開啟「Window > MCP for Unity > Toggle MCP Window」,按「Start Server」。第一次啟動時,視窗會詢問是否在背景啟動伺服器,這時按「Start」。當視窗顯示「Session Active」時,就代表伺服器已經和編輯器連上:

這時在專案資料夾執行 claude mcp list,UnityMCP 會顯示 Connected。重新開啟編輯器後,伺服器不會自己啟動,要再按一次「Start Server」。
讓 Claude Code 操作編輯器
Unity CLI 或 MCP for Unity 設定完成後,讓編輯器保持開啟,再到專案資料夾啟動 Claude Code,在 Prompt 裡交代要做的事與完成時要確認的結果:
1目前開啟的 Unity 編輯器裡有專案 C:\UnityProjects\CatCli。請操作這個執行中的編輯器:
2新建場景 Assets/Scenes/Cat.unity,用內建的基本形狀拼一隻坐著的橘貓,
3寫一個讓貓繞 Y 軸每秒轉 45 度的腳本並掛上去。等編譯完成、確認 Console 沒有錯誤後,
4進入 Play Mode 截一張 Game View 的圖,再離開 Play Mode 並儲存場景。
用 unity command 時,Claude Code 會先載入 unity-cli skill,用 unity command scene create 建立場景,再多次用 unity command script eval 執行 C# 建立物件與材質。腳本編譯完成後,Claude Code 會進入 Play Mode、用 capture game_view 截圖,再讀取這張圖確認貓出現在畫面上:

接上 unity mcp 或 MCP for Unity 時,Claude Code 會改為呼叫 MCP 工具來建立場景、撰寫腳本與截圖,截圖後同樣會讀取圖片,確認貓出現在畫面上。
問題排除
| 症狀 | 原因 | 處理方式 |
|---|---|---|
Console 每 15 秒出現 Pipeline: Descriptor ... was not written,後面接著 icacls could not restrict |
專案放在 ReFS 格式的開發磁碟機,無法修改連接埠檔案的權限 | 把專案移到 NTFS 格式的磁碟 |
unity command 回報找不到專案的 Pipeline 執行個體 |
編輯器還在載入或重新編譯腳本 | 執行 unity status --until-ready 等待編輯器就緒 |
unity mcp configure 回報 already exists in user config |
已經有同名的設定 | 先執行 claude mcp remove --scope user unity-editor-mcp 再設定 |
透過 unity mcp 呼叫時失敗,Console 出現 ObjectDisposedException |
腳本重新編譯時,編輯器重新載入程式碼而中斷連線 | Agent 重試後就會成功,這個錯誤不會影響專案 |
MCP for Unity 截圖失敗,回報 resolves outside the Unity project root |
截圖路徑指定在專案資料夾外面 | 改存到專案資料夾裡,例如 Assets/Screenshots |
實測紀錄
測試任務是同一段 Prompt,內容和「讓 Claude Code 操作編輯器」一節相同,另外要求把截圖存到指定的路徑,並逐步回報每一步有沒有成功。unity mcp 執行了三次,其他兩種各執行兩次。每次執行前,我都把專案還原成只有預設場景的狀態,再用 claude -p 以 Sonnet 模型執行,並且只開放該接法需要的工具:
unity command:啟用 Unity Plugin,允許執行unity指令,不接任何 MCP 伺服器。unity mcp:啟用 Unity Plugin,只接unity mcp --tool-groups,並禁止執行終端機指令。- MCP for Unity:只接 MCP for Unity 的伺服器。
下表的回合數、時間與費用取自 claude -p 的結果紀錄,回合數是 Claude Code 送出請求、執行工具再讀取結果的往返次數。開場多用的 Token 是讓 Claude Code 只回覆「OK」時,第一個請求的輸入 Token 和沒接任何東西時的差距。同一格裡的數字依序是每一次執行的結果:
| 項目 | unity command |
unity mcp |
MCP for Unity |
|---|---|---|---|
| 開場載入的內容 | Unity Plugin | 44 個工具 | 49 個工具 |
| 開場多用的 Token | 1,707 | 965 | 2,344 |
| 回合數 | 13、13 | 44、34、24 | 29、20 |
| 完成時間 | 100、81 秒 | 83、89、54 秒 | 92、87 秒 |
| 費用 | 0.35、0.33 美元 | 0.35、0.59、0.36 美元 | 0.34、0.28 美元 |
| 截圖存放位置 | 專案內外都可以 | 專案內外都可以 | 只能存在專案資料夾內 |
| 腳本重新編譯時 | 沒有出現錯誤 | 三次都有呼叫失敗,Agent 重試後完成 | 沒有出現錯誤 |
每次執行的截圖都確認過畫面裡有貓。Claude Code 預設只先載入 MCP 工具的名稱,用到時才讀取完整定義,所以接上 MCP 伺服器時開場多用的 Token 不多。設定 ENABLE_TOOL_SEARCH=false 讓 Claude Code 一開始就載入全部的工具定義時,unity mcp 開場會多用 21,863 個 Token,MCP for Unity 則多用 45,454 個。
總結
讓 Agent 操作 Unity 編輯器時,如果用過 AI Assistant 套件的 MCP,就先移除舊設定,再依客戶端是否能執行終端機指令,以及專案的 Unity 版本來選擇接法。用 unity command 時,Claude Code 兩次都在 13 個回合內拼好貓並截圖確認,改接 unity mcp 時,腳本重新編譯會讓連線中斷,要靠 Claude Code 重試才完成。



