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 использует ту же схему mcpServers, что и Claude Desktop. Конфиг проекта приоритетнее глобального.

VS Code → Cline → MCP Servers → Edit

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

Щёлкните значок MCP Servers на боковой панели Cline, затем "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 использует массив объектов серверов, а не map.

~/.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 — эффект x10

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
Токенов на вызов: 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

Ещё

Ресурсы

📖 Читать официальный README на GitHub

🐙 Открытые задачи

🔍 Все 400+ MCP-серверов и Skills