mcp-unity MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

Scene and GameObject CRUD with transform controls
Component add/modify, material create/assign
EditMode + PlayMode test runner
Console log streaming
batch_execute for composing multiple tool calls atomically

라이브 데모

실제 사용 모습

unity-3.replay ▶ 준비됨

0/0

설치

클라이언트 선택

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

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

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

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

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

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

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

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

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

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

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

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

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

context_servers에 추가. 저장 시 Zed가 핫 리로드.

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

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: mcp-unity

How to build a simple scene from chat with minimal ceremony

👤 Indie Unity devs ⏱ ~15 min beginner

언제 쓸까: You want a Unity MCP without 100+ tools cluttering your context.

사전 조건

Unity 6 or later — unity.com/download
Node 18+ — nodejs.org or nvm
Install package from git URL — Package Manager > + > Add from git URL: https://github.com/CoderGamester/mcp-unity.git

흐름

Compose a scene

Create a new scene 'Playground'. Add a Plane, a Directional Light, and 3 cubes at positions (-2,0,0), (0,0,0), (2,0,0).✓ 복사됨

→ Scene appears, objects visible
Wire up interactions

Add a Rigidbody and BoxCollider to each cube. Make cube at origin kinematic.✓ 복사됨

→ Components visible on inspect
Run tests

run_tests mode=EditMode. Show failures.✓ 복사됨

→ Test output

결과: A working scene + passing tests, all in chat.

함정

batch_execute rollback behavior varies — not a real transaction — Assume partial success on error; verify after batch

함께 쓰기: github

How to author and instantiate prefabs from chat

👤 Unity devs building reusable assets ⏱ ~15 min intermediate

언제 쓸까: You want the agent to maintain a prefab library.

흐름

Create a prefab

Build a GameObject 'Enemy' with Rigidbody + EnemyAI component, then create_prefab from it at Assets/Prefabs/Enemy.prefab.✓ 복사됨

→ Prefab file created
Instantiate

add_asset_to_scene Assets/Prefabs/Enemy.prefab at 5 random positions within 50 units of origin.✓ 복사됨

→ 5 enemies placed

결과: A reusable Enemy prefab + 5 placed instances.

How to iterate on a fix with run_tests in a tight loop

👤 Unity devs with test coverage ⏱ ~15 min intermediate

언제 쓸까: Bug + test exists; want fast red-green-refactor.

흐름

See the failure

run_tests mode=EditMode filter='EnemyAI_ShouldPatrol'. Show the stack.✓ 복사됨

→ Failing assertion with line
Edit and retest

Apply the minimal fix, save, and rerun the test.✓ 복사됨

→ Green test

결과: Green test, confidence in fix.

함께 쓰기: github

조합

다른 MCP와 조합해 10배 효율

unity-3 + github

Run tests, then commit + PR the fix

Fix EnemyAI test failure, commit on branch fix/enemy-patrol, open a PR.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
create_scene	name: str	Start a new scene	free
load_scene	path: str	Open existing scene	free
get_gameobject	name_or_id: str	Look up one object	free
update_gameobject	id, props	Rename, re-parent, toggle active	free
update_component	target, component, values	Tweak component fields	free
create_prefab	source_id, path	Capture an object as prefab	free
add_asset_to_scene	path, position?, rotation?	Instantiate an asset/prefab	free
run_tests	mode: 'EditMode'\|'PlayMode', filter?	Unit tests	free
get_console_logs	since_ms?	Check errors	free
batch_execute	calls: Call[]	Compose several tool calls	free

비용 및 제한

운영 비용

API 쿼터: None — local only
호출당 토큰: Small; this MCP has a tight tool list
금액: Free (open source)
팁: Batch related ops via batch_execute to reduce round trips.

보안

권한, 시크릿, 파급범위

최소 스코프: Local project access only

자격 증명 저장: None

데이터 외부 송신: Localhost; LLM sees whatever your tool returns

절대 부여 금지: Expose the Node bridge to non-loopback

PlayMode tests run game code — side effects possible. Commit first.

문제 해결

자주 발생하는 오류와 해결

Unity 'package could not be resolved'

Requires Unity 6 or later. Check version; git URL install fails on older editors.

Node bridge crashes on startup

Requires Node 18 + npm 9. Check 'node -v' and upgrade.

확인: node -v

Tests don't appear

Test assemblies must be defined in Assembly Definition files referencing TestRunner.

대안

mcp-unity 다른 것과 비교

대안	언제 쓰나	단점/장점
MCP for Unity (CoplayDev)	You want the largest Unity tool surface with physics/VFX coverage	More tools = more context cost
Unity-MCP (IvanMurzak)	You need Roslyn-backed one-shot C# execution	More power, more risk

mcp-unity