unity-mcp MCP — 使用場景, 安裝 & 即時演示

為什麼要用

核心特性

40+ granular Unity Editor tools (scene, assets, scripts, tests, physics, UI, VFX)
Safe C# script apply_text_edits with validation before write
Read the Unity console (errors/warnings) and trigger domain reloads
Run EditMode and PlayMode tests and read results
Supports multiple Unity instances with per-instance routing

即時演示

實際使用效果

unity.replay ▶ 就緒

0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示，然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "unity",
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列，而非映射。

~/.config/zed/settings.json

{
  "context_servers": {
    "unity": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/CoplayDev/unity-mcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add unity -- TODO 'See README: https://github.com/CoplayDev/unity-mcp'

一行命令搞定。用 claude mcp list 驗證，claude mcp remove 移除。

使用場景

實戰用法： unity-mcp

How to prototype a Unity scene from a text description

👤 Game designers, solo devs, hackathon teams ⏱ ~20 min intermediate

何時使用： You want to go from 'low-poly forest with a player and 5 patrolling enemies' to a runnable scene without wiring every GameObject by hand.

前置條件

Unity 2021.3 LTS or newer, Python 3.10+, uv — Install uv via brew install uv; Unity from unity.com/download
Install the Unity package — Window > Package Manager > + > Add from git URL: https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

步驟

Describe the scene you want

Create a new scene called 'ForestDemo'. Add a low-poly terrain 200x200, a player capsule at origin with a rigidbody, and 5 cube enemies placed randomly between (-50,-50) and (50,50).✓ 已複製

→ Scene created, GameObjects appear in Hierarchy, Unity reflects changes live
Ask for behavior scripts

Create a C# script EnemyPatrol.cs that moves between two random waypoints, and attach it to every Enemy* GameObject.✓ 已複製

→ New script compiles cleanly, attached to enemies
Enter Play mode and iterate

Enter Play mode for 5 seconds, then read the console and tell me if anything threw.✓ 已複製

→ Runtime log returned, Claude proposes concrete fixes for any NullReferenceException

結果： A runnable prototype scene with scripted enemies — under 15 minutes of chat.

注意事項

Script edits reject because of compile errors cascading — Ask Claude to run manage_script validate before apply_text_edits
Domain reload wipes runtime state mid-session — Save scene explicitly before script edits; use refresh_unity afterwards

搭配使用： filesystem · github

How to diagnose and fix Unity compile/runtime errors from chat

👤 Unity developers stuck on a red console ⏱ ~15 min intermediate

何時使用： The console is full of errors from a big refactor or a package update and you want a second pair of eyes.

步驟

Pull the console

Read the Unity console. Group errors by root cause.✓ 已複製

→ Grouped error categories with likely files identified
Read the offending script

Open the top script mentioned, find the line, and explain why it breaks.✓ 已複製

→ Specific fix proposal referencing line numbers
Apply a minimal patch

Apply the smallest change to make it compile, then refresh Unity and re-read the console.✓ 已複製

→ Error count drops, no new errors introduced

結果： A green console and a diff you can review before committing.

注意事項

Claude proposes fixes that break API contracts for other scripts — Ask it to find references (find_in_file) before editing

搭配使用： github

How to run Unity EditMode/PlayMode tests and read failures

👤 Unity devs with a real test suite ⏱ ~15 min intermediate

何時使用： Before opening a PR or when CI is down and you want a quick local pass.

步驟

Kick off a test run

Run all EditMode tests in the Tests.EditMode assembly.✓ 已複製

→ Test job id returned, status streamed
Summarize failures

For each failing test, show the assertion message and the line it fired on.✓ 已複製

→ Per-test diagnosis
Fix the smallest failure first

Pick the failure most likely caused by my last change and propose a patch.✓ 已複製

→ Concrete edit suggestion

結果： A green test run with traceable edits.

注意事項

PlayMode tests need a different assembly — Specify EditMode vs PlayMode explicitly

搭配使用： github

組合

與其他 MCP 搭配，撬動十倍槓桿

unity + github

Scaffold a scene + scripts, commit the changes, open a PR for review

Build the EnemyPatrol feature in Unity, commit the new script and scene changes to a branch 'feature/enemy-patrol', and open a PR with a summary of what changed.✓ 已複製

unity + filesystem

Import a batch of 3D assets from a local folder and wire them into prefabs

Read /Downloads/kenney-nature-pack, import every .fbx into Assets/Models/, then create a prefab for each tree with a collider.✓ 已複製

unity + unity-2 + unity-3

Pick the Unity MCP that best matches your workflow — run only one at a time

Compare MCP for Unity vs CoderGamester mcp-unity for my 2D tilemap project, then keep the better one enabled.✓ 已複製

工具

此 MCP 暴露的能力

工具	輸入參數	何時呼叫	成本
manage_scene	action: 'create'\|'open'\|'save'\|'load', name?: str, path?: str	Any scene lifecycle change	free
find_gameobjects	query: str, scene?: str	Locate objects by name, tag, or component	free
manage_components	target: str, action: 'add'\|'remove'\|'modify', component: str, values?: obj	Attach or tweak components	free
manage_script	action: 'create'\|'read'\|'delete', path: str, body?: str	Full-file script writes — use apply_text_edits for partial	free
apply_text_edits	path: str, edits: Edit[]	Surgical patches; safer than full rewrites	free
read_console	since_ms?: int	Inspect errors/warnings after any change	free
run_tests	mode: 'EditMode'\|'PlayMode', filter?: str	Start a test run; poll with get_test_job	free
refresh_unity		After creating/modifying scripts or assets	free
manage_asset	action, path, ...	Import/move/delete assets	free
unity_docs	query: str	Look up Unity API docs inline	free

成本與限制

運行它的成本

API 配額: No remote API — runs entirely on your machine
每次呼叫 Token 數: Reading the scene hierarchy: 500–3000 tokens. Script reads: depends on file size
費用: Free (open source, MIT)
提示: Disable tools you won't use (e.g. manage_vfx, manage_probuilder) via the tool allowlist to shrink the prompt footprint.

安全

權限、密鑰、影響範圍

最小權限： local filesystem write to your Unity project

憑證儲存： None required — localhost HTTP only

資料出站： Localhost only (http://localhost:8080/mcp). No telemetry by default.

切勿授予： access to Unity projects outside the active one

AI-driven script edits can break your project — commit before long sessions.
run_tests in PlayMode executes game code; treat it like 'play' would, with full side effects.

故障排查

常見錯誤與修復

Claude can't connect: ECONNREFUSED localhost:8080

Unity Editor must be open with the MCP package loaded. Check Window > MCP for Unity > Status.

驗證： curl http://localhost:8080/mcp/ping

apply_text_edits reports 'file changed on disk'

Another tool modified the file. Re-read with manage_script before editing again.

refresh_unity hangs forever

Usually a compile error locking the domain reload. Open Unity, fix the red script, then retry.

驗證： Check Unity console manually

Package Manager 'Could not resolve git URL'

Behind a proxy or no git on PATH. Install git and retry, or use OpenUPM install instead.

驗證： git --version

替代方案

unity-mcp 對比其他方案

替代方案	何時用它替代	權衡
Unity-MCP (IvanMurzak)	You want CLI-driven setup and Roslyn-based C# execution	Smaller community than Coplay's, different tool surface
mcp-unity (CoderGamester)	You want a simpler tool set focused on scene manipulation and tests	Fewer tools, less coverage of materials/VFX

unity-mcp

為什麼要用

核心特性

即時演示

實際使用效果

安裝

選擇你的客戶端

使用場景

實戰用法： unity-mcp

How to prototype a Unity scene from a text description

前置條件

步驟

注意事項

How to diagnose and fix Unity compile/runtime errors from chat

步驟

注意事項

How to run Unity EditMode/PlayMode tests and read failures

步驟

注意事項

組合

與其他 MCP 搭配，撬動十倍槓桿

工具

此 MCP 暴露的能力

成本與限制

運行它的成本

安全

權限、密鑰、影響範圍

故障排查

常見錯誤與修復

替代方案

unity-mcp 對比其他方案

更多

資源