🎮

dev.breadpack.UnityMcpBridge

MCP (Model Context Protocol) Bridge for Unity Editor — connect AI agents to Unity Editor

0 installs

Trust: 34 — Low

Gaming

Ask AI about dev.breadpack.UnityMcpBridge

I know everything about dev.breadpack.UnityMcpBridge. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

Unity MCP

Unity MCP (Model Context Protocol) Bridge — Connect AI agents to Unity Editor.

Architecture

AI Agent (Claude, Cursor, etc.)
    ↕ stdio (MCP protocol)
UnityMcpBridge (.NET)
    ↕ TCP (binary protocol)
Unity Editor (UnityMcpEditor package)

Two components are required:

Component	Role	Install method
UnityMcpBridge	.NET MCP server (stdio ↔ TCP)	`npx` / `dotnet tool` / clone
UnityMcpEditor	Unity Editor plugin (TCP server + handlers)	UPM git URL

Claude Code Plugin 설치 (권장)

Claude Code에서 플러그인으로 설치하면 MCP 서버, Skills, Agents, Hooks가 한 번에 구성됩니다.

Step 1. Unity Editor 패키지 설치

Unity 6000.0+ 필요

Unity Editor > Window > Package Manager > + > Add package from git URL:

https://github.com/breadpack/UnityMcp.git?path=UnityMcpEditor

Step 2. Claude Code에서 플러그인 설치

Claude Code 세션 내에서:

/plugin install --from github:breadpack/UnityMcp

또는 프로젝트 .claude/settings.json에 등록:

{
  "enabledPlugins": {
    "unity-mcp": {
      "source": {
        "source": "github",
        "repo": "breadpack/UnityMcp"
      }
    }
  }
}

설치 시 아래 옵션을 프롬프트로 설정할 수 있습니다:

옵션	설명	기본
`unity_tcp_port`	Unity TCP 포트	`9876`
`auto_save_scene`	씬 변경 후 자동 저장	`false`
`check_compile_status`	도구 호출 전 컴파일 상태 체크	`true`
`check_domain_reload`	도구 호출 전 도메인 리로드 상태 체크	`true`
`max_wait_seconds`	컴파일/리로드 대기 최대 시간(초)	`60`

Step 3. 검증

Unity Editor를 연 상태에서 Claude Code에 다음과 같이 요청:

"Unity에 ping을 보내줘"

포함 구성요소

MCP 서버 (unity-bridge) — 45+ Unity 도구 (씬, 컴포넌트, 에셋, 빌드 등)

Agents 3종 — 특정 도메인 전문 에이전트

Agent	역할
`unity-scene-architect`	씬 설계, GameObject/컴포넌트/UI 구성
`unity-debugger`	에러 추적, Play Mode 검사, 성능 분석
`unity-asset-manager`	Material, Prefab, Addressable, 빌드 관리

Skills 6종 — 워크플로우 가이드 (슬래시 커맨드)

Skill	명령어
Scene Setup	`/unity-mcp:unity-scene-setup`
UI Build	`/unity-mcp:unity-ui-build`
Material Setup	`/unity-mcp:unity-material-setup`
Prefab Workflow	`/unity-mcp:unity-prefab-workflow`
Debug	`/unity-mcp:unity-debug`
Build & Deploy	`/unity-mcp:unity-build-deploy`

Hooks — 자동 상태 관리

SessionStart: Unity 연결 상태 체크 및 프로젝트 정보 출력
PreToolUse: 도구 호출 전 컴파일/도메인 리로드 감지. 진행 중이면 대기 후 재시도.
PostToolUse: 씬 변경 도구 실행 후 auto_save_scene=true 시 자동 저장.
PostToolUseFailure: 도구 실행 실패 시 연결 복구 진단.

사용 예시

> @unity-scene-architect 3D 플랫포머 기본 씬을 만들어줘. 바닥, 플레이어, 카메라.

> @unity-debugger 현재 씬의 에러 원인을 찾아줘.

> /unity-mcp:unity-build-deploy
> Windows 타겟으로 빌드해줘.

수동 설치 (플러그인 없이)

플러그인을 사용하지 않고 개별 도구에서 MCP 서버만 쓰고 싶다면:

Quick Start

Step 1. Install MCP Bridge

No pre-install needed — just configure and go (see Step 3).

Or install globally:

# npx (recommended, no .NET required)
npx -y unity-mcp-bridge

# dotnet tool (requires .NET 9.0+ SDK)
dotnet tool install -g dev.breadpack.UnityMcpBridge

Step 2. Install Unity Editor Package

Requires Unity 6000.0+ (Unity 6)

Open Unity Editor > Window > Package Manager > + > Add package from git URL:

https://github.com/breadpack/UnityMcp.git?path=UnityMcpEditor

Newtonsoft.Json (com.unity.nuget.newtonsoft-json) is auto-resolved as a dependency. No other prerequisites required.

Step 3. Configure your AI tool

Add MCP server configuration to your AI tool:

Claude Code (.mcp.json in project root)

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "unity-mcp-bridge"]
    }
  }
}

Or via CLI:

claude mcp add unity -- npx -y unity-mcp-bridge

Claude Desktop

Edit %APPDATA%/Claude/claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "unity-mcp-bridge"]
    }
  }
}

Cursor / VS Code (.cursor/mcp.json or .vscode/mcp.json)

{
  "mcpServers": {
    "unity": {
      "command": "npx",
      "args": ["-y", "unity-mcp-bridge"]
    }
  }
}

Using dotnet tool instead

If you installed via dotnet tool install -g, use the command directly:

{
  "mcpServers": {
    "unity": {
      "command": "unity-mcp-bridge"
    }
  }
}

Step 4. Verify

Open Unity Editor with the package installed, then ask your AI agent:

"Unity에 ping을 보내줘"

Alternative: Clone and Build

If you prefer to build from source:

git clone https://github.com/breadpack/UnityMcp.git
cd UnityMcp/UnityMcpBridge
dotnet run

Configure with:

{
  "mcpServers": {
    "unity": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/UnityMcp/UnityMcpBridge"]
    }
  }
}

Requires .NET 9.0+ SDK

Configuration

Environment Variable	Default	Description
`UNITY_TCP_PORT`	`9876`	TCP port to connect to Unity Editor

Example with custom port:

{
  "mcpServers": {
    "unity": {
      "command": "unity-mcp-bridge",
      "env": { "UNITY_TCP_PORT": "9877" }
    }
  }
}

Available Tools (35)

Observation (14)

Tool	Description
`unity_ping`	Check Unity Editor connection
`unity_get_hierarchy`	Get scene hierarchy
`unity_get_asset_hierarchy`	Inspect Prefab/Scene hierarchy without opening
`unity_get_component_details`	Get component property details
`unity_get_screen`	Get current screen info (Play Mode)
`unity_get_ui_tree`	Get UI Toolkit visual tree (Play Mode)
`unity_get_ugui_tree`	Get UGUI Canvas hierarchy
`unity_get_console_logs`	Get console log entries
`unity_get_available_actions`	List clickable UI actions (Play Mode)
`unity_take_screenshot`	Capture game view screenshot (Play Mode)
`unity_render_uxml`	Render UXML to image
`unity_refresh_assets`	Refresh AssetDatabase
`unity_addressable_add`	Add asset to Addressable group (requires package)
`unity_addressable_set_address`	Set Addressable asset address (requires package)

Scene Manipulation (10)

Tool	Description
`unity_create_gameobject`	Create new GameObject
`unity_delete_gameobject`	Delete GameObject (dryRun supported)
`unity_reparent_gameobject`	Change parent of GameObject
`unity_set_transform`	Set position / rotation / scale
`unity_set_active`	Activate / deactivate GameObject
`unity_select_gameobject`	Select and ping in Editor
`unity_save_scene`	Save current scene
`unity_load_scene`	Open scene (Single / Additive)
`unity_play_mode`	Enter / exit / toggle Play Mode
`unity_instantiate_prefab`	Instantiate prefab in scene

Component & Property (4)

Tool	Description
`unity_add_component`	Add component to GameObject
`unity_remove_component`	Remove component (dryRun supported)
`unity_set_property`	Set component property (dot-notation, array, asset ref)
`unity_set_asset_reference`	Set asset reference on component field

Material (2)

Tool	Description
`unity_create_material`	Create new Material asset
`unity_set_material_property`	Set material property (color, float, texture, vector)

Asset Management (1)

Tool	Description
`unity_manage_asset`	Move / copy / delete asset, create folder

Prefab (1)

Tool	Description
`unity_prefab_edit`	Enter / save / exit Prefab edit mode

Animation (1)

Tool	Description
`unity_animator_control`	Set Animator parameters, query state (Play Mode)

Build & Settings (2)

Tool	Description
`unity_build`	Build player (Windows, macOS, Linux, Android, iOS, WebGL)
`unity_project_settings`	Read / write PlayerSettings, QualitySettings, Physics, Time

Conditional Features

Addressables Support

To enable Addressable tools, add the scripting define symbol to your Unity project:

Edit > Project Settings > Player > Scripting Define Symbols
Add UNITY_MCP_ADDRESSABLES

Update

npx는 자동으로 최신 버전을 사용합니다. dotnet tool을 사용하는 경우:

dotnet tool update -g dev.breadpack.UnityMcpBridge

License

MIT