Unity MCP 安裝指南與使用

發表於 2026-03-21 分類於 unity

Unity MCP 安裝指南與使用

簡介

什麼是 Unity MCP？

MCP for Unity 是由 Coplay 開發並維護的開源專案，透過 Model Context Protocol（MCP） 將 AI 助手（Claude、Claude Code、Cursor、VS Code Copilot、GitHub Copilot CLI 等）與你的 Unity Editor 串接起來。

簡單來說，只要你開著 Unity 編輯器，就可以直接對 AI 說：「幫我建立一個有紅色、藍色和黃色方塊的場景」或「幫我寫一個簡單的玩家控制器」，AI 就能透過 MCP 協定直接操作你的 Unity 專案。

核心特性

自然語言控制：用文字描述任務，讓 AI 直接在 Unity 中執行
豐富工具集：管理資產、場景、材質、腳本、UI、動畫、著色器等
高效能批次執行：batch_execute 指令比逐一呼叫快 10 ～ 100 倍
可擴充自訂工具：支援 Roslyn 執行時期腳本驗證與自訂工具擴充
多 Unity 實例支援：可同時連接多個 Unity Editor 並指定目標實例
MIT 授權：完全開源免費

支援的 MCP 客戶端

Claude Desktop
Claude Code
Cursor
VS Code Copilot
GitHub Copilot CLI
Windsurf

系統要求

必要條件

項目	版本需求
Unity	2021.3 LTS 或更新版本
WSL 2	Windows 10 21H2 或更新版本
Docker Desktop	最新版本（需啟用 WSL 2 整合）
Git	任意版本（用於 clone 專案）

本指南採用 WSL + Docker 的方式在本機運行 MCP Server，無需在 Windows 主機上安裝 Python 或 uv，環境隔離性佳且易於維護。

安裝步驟

步驟 1：在 WSL 中以 Docker 啟動 MCP Server

開啟 WSL 終端機，依序執行以下操作。

抓取專案原始碼

將 unity-mcp clone 至本機，並切換至專案目錄：

1 2	git clone https://github.com/CoplayDev/unity-mcp.git cd unity-mcp

修改 docker-compose.yml

原始的 docker-compose.yml 啟動方式是直接執行 Python 腳本，在 WSL 環境下需要調整為使用內建進入點，以確保容器可正確啟動。

原始內容：

version: "3.9"

services:
  unity-mcp-server:
    build:
      context: .
      dockerfile: Server/Dockerfile
    ports:
      - "8080:8080"
    restart: unless-stopped
    environment:
      - PYTHONPATH=/app/Server/src
    command: ["uv", "run", "python", "src/main.py", "--transport", "http", "--http-host", "0.0.0.0", "--http-port", "8080"]

修改後（移除 environment 區段，並改用簡化的啟動指令）：

version: "3.9"

services:
  unity-mcp-server:
    build:
      context: .
      dockerfile: Server/Dockerfile
    ports:
      - "8080:8080"
    restart: unless-stopped
    command: ["--transport", "http", "--http-url", "http://0.0.0.0:8080"]

Build Image 並啟動容器

第一次執行時需要 Build Docker Image，依網路與機器效能不同，可能需要數分鐘：

1	docker compose up -d

確認容器正常運行

執行以下指令列出目前運行中的容器：

docker ps

確認清單中出現 unity-mcp-server 容器，且狀態欄位顯示 Up 即代表啟動成功。

確認 Server 健康狀態

透過 curl 向 Server 發送健康檢查請求：

1	curl http://localhost:8080/health

收到正常回應即代表 MCP Server 已順利啟動，可以接受連線。

步驟 2：在 Unity 中安裝套件

MCP Server 啟動完成後，接著要在 Unity 編輯器內安裝對應的 Client 套件，讓 Unity 能夠與 Server 溝通。

開啟 Unity 編輯器，依序選擇：

Window > Package Manager > Package Management...

+ > Add package from git URL...

在輸入框中貼上以下 Git URL（正式版）：

1	https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

若需要搶先體驗最新測試版（beta）功能，可改用：

1	https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#beta

點擊 Add 後等待 Unity 下載並匯入套件，完成後即可在 Package Manager 中看到 MCP for Unity。

其他安裝方式

Unity Asset Store：
前往 MCP for Unity Asset Store 頁面，點擊 Add to My Assets，再透過 Window > Package Manager 匯入。

OpenUPM：
1
openupm add com.coplaydev.unity-mcp

步驟 3：設定 MCP 客戶端連線

套件安裝完成後，最後一步是將 Unity 與你的 AI 工具（MCP 客戶端）完成對接。

在 Unity 中開啟 Window > MCP for Unity > Toggle MCP Window，進行連接設置。

填入 http://localhost:8080/mcp 作為 MCP Server URL，以及選擇 MCP Client：

連線成功後，即可在你的 MCP 客戶端（Claude Desktop、Cursor、VS Code Copilot 等）對 AI 下達自然語言指令，讓它直接操作 Unity 編輯器。

以 GitHub Copilot CLI 為例，可透過以下方式確認是否已成功連接 MCP Server：

手動設定（若自動設定失敗）

若自動設定流程無法正常運作，可手動將以下設定加入 MCP 客戶端的設定檔。

使用 WSL Docker 運行 Server 時，統一採用 HTTP 模式連線至 localhost:8080。

HTTP 模式（適用 Claude Desktop、Cursor、Windsurf）

{
  "mcpServers": {
    "unityMCP": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

VS Code 設定

{
  "servers": {
    "unityMCP": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

實際演示

現在我們可以像開頭說的，直接對 AI 說：「幫我建立一個有紅色、藍色和黃色方塊的場景」，AI 就能透過 MCP 協定直接操作你的 Unity 專案。

可用工具一覽

安裝完成後，AI 助手可透過以下工具操作你的 Unity 專案：

場景與物件管理

工具	說明
`manage_scene`	建立、載入、儲存場景，查詢場景階層
`manage_gameobject`	新增、修改、刪除 GameObject，管理元件屬性
`find_gameobjects`	依名稱、標籤或條件搜尋場景中的物件
`manage_components`	新增、移除、設定 GameObject 上的元件
`manage_prefabs`	建立、修改、實例化 Prefab

資產管理

工具	說明
`manage_asset`	搜尋、建立、修改專案資產
`manage_material`	建立與設定材質屬性
`manage_texture`	管理貼圖資產
`manage_shader`	建立與設定著色器

腳本開發

工具	說明
`create_script`	建立新的 C# 腳本
`manage_script`	讀取與修改腳本內容
`delete_script`	刪除腳本
`validate_script`	驗證腳本語法正確性
`script_apply_edits`	套用腳本編輯
`apply_text_edits`	通用文字編輯工具
`find_in_file`	在檔案中搜尋內容

動畫、UI 與視覺效果

工具	說明
`manage_animation`	建立與設定動畫 Clip、Animator 控制器
`manage_ui`	管理 Unity UI 元件
`manage_vfx`	設定視覺特效（VFX Graph）
`manage_camera`	設定相機，支援 Cinemachine
`manage_graphics`	後處理、光照烘焙、渲染管線設定（33 項操作）

編輯器與專案管理

工具	說明
`manage_editor`	控制 Play Mode、暫停，管理標籤 / Layer
`manage_packages`	安裝、移除、搜尋 Unity 套件
`execute_menu_item`	執行 Unity 選單項目
`read_console`	讀取 Unity Console 輸出
`refresh_unity`	刷新 AssetDatabase
`run_tests`	執行 Unity 測試
`batch_execute`	批次執行多個操作（效能提升 10 ～ 100 倍）
`manage_tools`	即時切換工具群組的啟用狀態

API 驗證

工具	說明
`unity_reflect`	透過反射即時查詢 C# API 資訊
`unity_docs`	取得官方 Unity 文件（ScriptReference、Manual）

效能提示：執行多個操作時，建議使用 batch_execute — 比逐一呼叫快 10 ～ 100 倍！

多 Unity 實例管理

MCP for Unity 支援同時連接多個 Unity Editor 實例，方便在多專案環境下工作。

請 AI 查詢 unity_instances 資源以列出目前連線的實例
使用 set_active_instance，傳入 Name@hash 格式（例如 MyProject@abc123）指定目標實例
後續所有工具呼叫都會路由至指定的實例

進階功能：Roslyn 腳本驗證

啟用 Roslyn 後，AI 可在執行前進行嚴格驗證，即時偵測未定義的命名空間、型別和方法。

一鍵安裝（推薦）

開啟 Window > MCP for Unity，切換至 Scripts/Validation 頁籤，找到 Runtime Code Execution (Roslyn) 區塊，點擊 Install Roslyn DLLs。

系統會自動下載必要的 NuGet 套件，並將 DLL 放置於 Assets/Plugins/Roslyn/。

也可從選單執行：Window > MCP For Unity > Install Roslyn DLLs

手動安裝

安裝 NuGetForUnity
透過 Window > NuGet Package Manager 安裝 Microsoft.CodeAnalysis v5.0
同時安裝 SQLitePCLRaw.core 與 SQLitePCLRaw.bundle_e_sqlite3 v3.0.2
前往 Player Settings > Scripting Define Symbols，加入 USE_ROSLYN
重新啟動 Unity

常見問題與排解

問題	解決方式
Unity Bridge 無法連線	確認 `Window > MCP for Unity` 狀態，嘗試重啟 Unity
Docker 容器無法啟動	檢查 `docker compose logs unity-mcp-server` 查看錯誤輸出
Server 健康檢查失敗	確認容器正在運行（`docker ps`），並確認 port 8080 沒有被其他程式佔用
客戶端無法連線	確認 `curl http://localhost:8080/health` 有正常回應，URL 與設定一致
WSL 無法存取 localhost	確認 Docker Desktop 已啟用 WSL 2 整合（Settings > Resources > WSL Integration）

更多詳細排解指南：

修復 Cursor、VSCode 及 Windsurf 連線問題（uv/Python 安裝、PATH 設定）
修復 Claude Code 連線問題
常見安裝問題 FAQ（macOS dyld 錯誤等）

仍有問題？提交 Issue 或加入 Discord 社群。

安全性說明

MCP for Unity 的網路設定採用預設封閉原則，以確保安全：

HTTP Local 模式：預設只允許本機回環位址（127.0.0.1、localhost、::1）
若需綁定所有網路介面（0.0.0.0、::），需在 Advanced Settings 中明確啟用 Allow LAN Bind
HTTP Remote 模式：預設要求使用 https:// 加密傳輸
若要使用明文 http:// 進行遠端連線，需明確啟用 Allow Insecure Remote HTTP

免責聲明：本專案為 Unity Editor 的免費開源工具，與 Unity Technologies 無從屬關係。

Unity MCP 安裝指南與使用

簡介

什麼是 Unity MCP？

核心特性

支援的 MCP 客戶端

系統要求

必要條件

安裝步驟

步驟 1：在 WSL 中以 Docker 啟動 MCP Server

步驟 2：在 Unity 中安裝套件

步驟 3：設定 MCP 客戶端連線

手動設定（若自動設定失敗）

HTTP 模式（適用 Claude Desktop、Cursor、Windsurf）

VS Code 設定

實際演示

可用工具一覽

場景與物件管理

資產管理

腳本開發

動畫、UI 與視覺效果

編輯器與專案管理

API 驗證

多 Unity 實例管理

進階功能：Roslyn 腳本驗證

一鍵安裝（推薦）

手動安裝

常見問題與排解

安全性說明

相關資源