Unity MCP 設定教學:比較 Unity CLI 與 MCP for Unity,讓 Claude Code 操作編輯器並截圖確認

摘要

Unity AI Assistant 套件內建的 MCP 伺服器已經棄用,官方改由免費的 Unity CLI 接手。能執行終端機指令的 Claude Code 可以直接用 Unity CLI 的指令操作編輯器,只能呼叫 MCP 工具的客戶端改接 Unity CLI 內建的 MCP 伺服器,專案還在 Unity 6 以前的版本時則可以改裝社群的 MCP for Unity。三種接法都能讓 Agent 建立場景、寫腳本,再截下遊戲畫面確認結果。

文章目錄

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 送出操作時經過的程式:

三種接法的連線路徑:unity command 與 unity mcp 經 Unity CLI 連到 Pipeline 套件,MCP for Unity 經 Python 伺服器連到自己的套件,已棄用的 relay_win.exe 連到 AI Assistant 套件

移除 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 Editor 的狀態為 ready,接著 capture game_view 存下 1280x720 的截圖

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:

終端機顯示 unity-editor-mcp 的範圍是 User config,狀態為 Connected,參數為 mcp –tool-groups

預設的 --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:

Package Manager 的 Packages - Coplay 底下有 MCP for Unity 10.3.0,來源標示為 Git

設定 Claude Code

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

MCP for Unity Setup 的系統需求頁,Python 3.15.1、uv 0.13.6 與 Git 都顯示綠燈

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

Configure MCP Clients 頁只勾選 Claude Code,其他客戶端都取消勾選

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」時,就代表伺服器已經和編輯器連上:

MCP for Unity 視窗的 Transport 為 HTTP Local,Local Server 旁是 Stop Server 按鈕,下方顯示 Session Active (CatCoplay)

這時在專案資料夾執行 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 截圖,再讀取這張圖確認貓出現在畫面上:

Claude Code 截下的 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 重試才完成。

延伸閱讀

Ted Liou

Ted Liou

現役軟體工程師,分享 Unity 與 AI 的技術開發經驗。

留言