Unity MCP

Unity Editor와 Claude Code를 연결하는 MCP (Model Context Protocol) 패키지.

Architecture

Claude Code ←(STDIO)→ Node.js MCP Server ←(WebSocket :8090)→ Unity Editor (C#)

Project Structure

unity-mcp/
├── server/                  # Node.js MCP 브릿지 서버 (TypeScript)
│   ├── bin/cli.ts           # CLI 엔트리포인트
│   ├── src/
│   │   ├── index.ts         # MCP 서버 엔트리포인트
│   │   ├── unity-bridge.ts  # WebSocket 클라이언트 (Unity 연결)
│   │   ├── types.ts         # 요청/응답 타입 정의
│   │   └── tools/index.ts   # 91개 도구 정의
│   └── build/               # 컴파일된 JS 출력
└── unity-package/           # Unity 패키지 (C#)
    └── Editor/
        ├── McpServer.cs     # WebSocket 서버 (연결/디스패치)
        ├── McpServerMenu.cs # 에디터 메뉴 통합
        ├── McpSettings.cs   # 설정 관리
        ├── ConsoleLogBuffer.cs  # 콘솔 로그 버퍼
        ├── ShaderGraphHelper.cs # ShaderGraph 유틸리티
        ├── IToolHandler.cs  # 도구 핸들러 인터페이스
        └── Handlers/        # 90개 핸들러 구현

Installation

1. Unity Package

Packages/manifest.json에 추가:

"com.jaewon.mcp-unity": "https://github.com/jaewonjung6446/unity-mcp.git?path=unity-package"

• Unity 2022.3 이상 필요
• 의존성: com.unity.nuget.newtonsoft-json, com.unity.editorcoroutines

2. MCP Server 빌드

cd server
npm install
npm run build

3. MCP Config

.mcp.json:

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["D:\\Unity\\Izakoza\\unity-mcp\\server\\build\\cli.js"]
    }
  }
}

Multiple Unity Projects (다중 프로젝트 설정)

한 로컬에서 여러 Unity 프로젝트의 MCP를 동시에 실행하려면 각각 다른 포트를 사용해야 합니다.

1. Unity 프로젝트별 포트 설정

각 Unity 프로젝트의 ProjectSettings/McpUnitySettings.json:

Project A:

{ "Port": 8090 }

Project B:

{ "Port": 8091 }

2. MCP 서버 설정

.mcp.json에서 --port 또는 -p 인자로 포트 지정:

{
  "mcpServers": {
    "unity-project-a": {
      "command": "node",
      "args": ["D:\\Unity\\unity-mcp\\server\\build\\cli.js", "--port", "8090"]
    },
    "unity-project-b": {
      "command": "node",
      "args": ["D:\\Unity\\unity-mcp\\server\\build\\cli.js", "--port", "8091"]
    }
  }
}

포트 우선순위

1. 명령줄 인자 (--port) — 최우선
2. ProjectSettings/McpUnitySettings.json 설정 파일
3. 기본값: 8090

Available Tools (91)

Editor Control (7)

Tool	Description
get_state	에디터 상태 (플레이 모드, 활성 씬, 플랫폼)
get_selection	현재 선택된 오브젝트
set_selection	에디터 선택 변경/해제 (다중 선택, 에셋 선택)
pause_editor	Play Mode 일시정지/해제
step_frame	일시정지 중 1프레임 전진
undo_redo	실행 취소/다시 실행 (최대 20단계)
clear_console	콘솔 창 및 로그 버퍼 클리어

Scene (6)

Tool	Description
open_scene	씬 열기 (additive 옵션)
close_scene	씬 닫기
save_scene	활성 씬 저장
get_scenes_list	빌드 설정/로드된/전체 씬 목록
get_scene_hierarchy	씬 계층구조 스냅샷
set_scene_view_camera	Scene View 카메라 제어 (위치, 회전, 줌, 프리셋 뷰)

GameObject (9)

Tool	Description
get_game_object	GameObject 정보 (ID/이름/경로)
create_game_object	GameObject 생성 (empty, primitive, 위치/회전/스케일)
delete_game_object	GameObject 삭제 (Undo 지원)
set_game_object_property	속성 설정 (이름, 태그, 레이어, 위치, 회전, 스케일 등)
duplicate_game_object	복제 (개수, 오프셋 옵션)
group_game_objects	여러 오브젝트를 빈 부모로 그룹화
align_game_object	축 기준 정렬 (min/max/center/first)
set_parent	부모-자식 관계 변경/해제
focus_game_object	Scene View에서 오브젝트 포커스

Component (5)

Tool	Description
get_component_data	컴포넌트 직렬화 필드 값 읽기
add_component	컴포넌트 추가 (Rigidbody, AudioSource 등)
remove_component	컴포넌트 제거
set_component_property	컴포넌트 프로퍼티 설정 (int, float, Color, Vector 등)
find_objects_by_criteria	태그/레이어/컴포넌트/이름으로 오브젝트 검색

Prefab (3)

Tool	Description
open_prefab	프리팹 편집 모드 열기
create_prefab	씬 오브젝트로 프리팹 에셋 생성
instantiate_prefab	프리팹을 씬에 인스턴스화

Asset Management (13)

Tool	Description
create_script	C# 스크립트 생성
execute_code	C# 코드 실행
get_asset_contents	에셋 내용 읽기
get_asset_importer	임포터 설정 조회
copy_asset	에셋 복사
import_asset	에셋 리임포트
delete_asset	에셋/폴더 삭제
move_asset	에셋 이동/이름 변경
create_folder	폴더 생성 (재귀)
get_asset_dependencies	에셋 의존성 조회
find_references	에셋 참조 역검색
get_asset_preview	에셋 미리보기 썸네일 이미지
refresh_assets	AssetDatabase 새로고침 (Ctrl+R)

Search & Validation (4)

Tool	Description
search	에셋 또는 씬 오브젝트 검색
screenshot	Scene/Game 뷰 스크린샷 캡처
test_active_scene	활성 씬 검증 (누락 스크립트, 머티리얼 등)
get_missing_references	씬/에셋에서 누락 참조 스캔

Shader Graph (5)

Tool	Description
create_shader_graph	ShaderGraph 생성 (URP Lit/Unlit/Canvas 템플릿)
add_shader_graph_node	노드 추가 (SampleTexture2D, Color, Multiply 등)
connect_shader_graph_nodes	노드 간 연결
add_shader_graph_property	프로퍼티 추가 (Color, Float, Texture2D 등)
get_shader_graph_node_types	지원 노드 타입/슬롯 정보 조회

Material & Rendering (7)

Tool	Description
create_material	머티리얼 생성 (셰이더 지정)
set_material_property	머티리얼 프로퍼티 설정 (color, float, texture 등)
set_game_object_material	GameObject에 머티리얼 할당
analyze_scene	씬 분석 (렌더러, 머티리얼, 셰이더, 라이트)
get_render_settings	렌더 설정 조회 (ambient, fog, skybox, reflections)
set_render_settings	렌더 설정 변경 (fog, ambient, skybox 등)
set_light_property	라이트 프로퍼티 설정 (타입, 색상, 강도, 그림자 등)

Volume / Post-Processing (2)

Tool	Description
get_volume_settings	URP Volume 설정 조회 (Bloom, Vignette 등)
set_volume_component	Volume 컴포넌트 설정 (Bloom, ColorAdjustments 등)

UI (9)

Tool	Description
create_ui_element	UI 요소 생성 (Text, Button, Slider 등, Canvas 자동 생성)
find_ui_elements	Canvas UI 요소 스캔 (경로, 타입, 상태)
inspect_ui_layout	UI 레이아웃 이슈 검출 (겹침, 화면 밖, 작은 터치 영역)
click_ui_element	UI 클릭 시뮬레이션 (Play Mode)
set_ui_input	InputField 텍스트 입력 (Play Mode)
get_ui_state	UI 요소 상태 조회 (Button, Toggle, Slider 등)
drag_ui_element	UI 드래그 앤 드롭 시뮬레이션 (Play Mode)
scroll_ui	스크롤 이벤트 시뮬레이션 (Play Mode)
set_ui_value	Slider/Toggle/Dropdown/Scrollbar 값 설정

QA & Play Mode (6)

Tool	Description
set_play_mode	Play Mode 진입/종료
get_console_logs	콘솔 로그 조회 (error, warning, exception 필터)
wait_for_seconds	대기 (0.1~30초)
wait_until	조건 충족까지 대기 (오브젝트 활성화, 텍스트 매칭 등)
simulate_input	키보드/마우스 입력 시뮬레이션 (Play Mode)
set_time_scale	Time.timeScale 설정 (슬로모션, 배속)

Animation (2)

Tool	Description
get_animator_state	Animator 상태, 전환 정보, 파라미터 값 조회
set_animator_parameter	Animator 파라미터 설정 (Float, Int, Bool, Trigger)

Physics (3)

Tool	Description
raycast	물리 레이캐스트 (월드/스크린 좌표, 다중 히트)
set_rigidbody_property	Rigidbody/2D 프로퍼티 설정 (질량, 드래그, 중력 등)
apply_force	Rigidbody에 힘 적용 (Force, Impulse, VelocityChange)

Audio (2)

Tool	Description
get_audio_sources	씬 내 모든 AudioSource 정보 조회
play_audio	오디오 재생/정지/일시정지 (클립 변경 가능)

Navigation (2)

Tool	Description
get_navmesh_info	NavMesh 정보, NavMeshAgent/Obstacle 조회
set_navmesh_destination	NavMeshAgent 목적지 설정/정지 (Play Mode)

Scene Systems (2)

Tool	Description
get_particle_system_info	ParticleSystem 정보 (모듈 설정, 상태, 파티클 수)
get_terrain_info	Terrain 정보 (크기, 해상도, 레이어, 트리)

Project Info (4)

Tool	Description
get_project_settings	프로젝트 설정 조회 (player, quality, physics, time)
get_packages	설치된 패키지 목록
get_build_settings	빌드 설정 (타겟 플랫폼, 씬, 개발 모드)
get_performance_stats	런타임 성능 통계 (FPS, 메모리, 오브젝트 수)

Development

cd server
npm install
npm run build          # TypeScript 컴파일
npm run watch          # 변경 감지 자동 빌드
node build/cli.js      # 서버 실행