Unity MCP 빌트인 도구 완전 레퍼런스 — 51개 도구 파라미터·활성화 가이드

작성자:

Unity AI 완전 정복 시리즈
1편 — Unity AI Assistant 완전 입문: Ask·Plan·Agent 모드 차이점과 언제 무엇을 쓸까
2편 — Unity MCP 완전 가이드: Claude Code·Codex·Gemini·Cursor를 Unity Editor와 연결하기
3편 — Unity MCP 커스텀 도구 만들기: McpTool Deep Dive와 4가지 등록 방식
4편 — Unity Skills 시스템으로 AI 워크플로우 자동화하기: SKILL.md 완전 가이드
Appendix — Unity MCP 빌트인 도구 완전 레퍼런스 — 51개 도구 파라미터·활성화 가이드 (현재 글)
5편 — Unity AI Assistant Project Overview 자동 생성 — AI가 내 프로젝트를 이해하게 만드는 방법
6편 — Unity AI Assistant × Profiler — 성능 병목을 자연어로 진단하는 완전 가이드

Claude Code나 Cursor가 Unity Editor에 접속할 때 실제로 무슨 도구를 호출할 수 있는지 — 공식 문서에는 전체 목록이 없습니다. 이 글은 com.unity.ai.assistant @2.7(Unity 6.3) 패키지 소스를 직접 뜯어보며 확인한 내용입니다. 빌트인 MCP 도구 51개 전체의 파라미터·타입·기본값·활성화 방법을 개발자 레퍼런스 형태로 정리했습니다.

TL;DR
– Unity MCP 빌트인 도구는 총 53개(소스 확인 51개), Core·Assets·Assistant·Debug & Diagnostics·Editor 5개 그룹으로 구성됩니다.
– 기본 활성(EnabledByDefault = true) 도구는 7개뿐. 나머지는 Project Settings에서 직접 켜야 합니다.
– 등록 메커니즘은 2종: [McpTool] 어트리뷰트 직접 선언 vs AgentToolMcpAdapter 브리징.
– AssetGeneration 도구군은 Unity Credits를 소모하며, Profiler 도구군은 Profiler 창에 캡처 데이터가 있어야 동작합니다.
– 커스텀 도구 제작 방법은 McpTool Deep Dive를 참고하세요.

목차

도구 활성화 방법

Unity MCP 빌트인 도구는 두 가지 상태로 나뉩니다.

상태 의미
기본 활성 (EnabledByDefault = true) MCP 연결 직후 바로 사용 가능
수동 활성 필요 (EnabledByDefault = false) 아래 절차로 직접 켜야 함

수동 활성화 절차:

  1. Unity Editor 상단 메뉴 → Edit > Project Settings
  2. 좌측 목록에서 AI > Unity MCP 선택
  3. Tools 탭 클릭
  4. 활성화할 도구 옆 체크박스를 켬
  5. 외부 AI 클라이언트(Claude Code, Cursor 등)에서 MCP 연결 재시작

기본 활성 도구 7개:

도구 ID 그룹
Unity.RunCommand Core
Unity.GetConsoleLogs Debug & Diagnostics
Unity.Camera.Capture Editor
Unity.SceneView.Capture2DScene Editor
Unity.SceneView.CaptureMultiAngleSceneView Editor
Unity.AssetGeneration.GenerateAsset Assets
Unity.AssetGeneration.GetModels Assets

기본 활성 7개는 MCP 연결 직후 바로 쓸 수 있습니다. AI 캡처 도구 3개, AssetGeneration 도구 2개, 콘솔 조회 1개, 코드 실행 1개 — 개발 중 가장 자주 필요한 것들로 추렸다는 인상입니다. 나머지 44개는 프로젝트 필요에 따라 골라서 켜는 방식입니다.

AssetGeneration 주의: GenerateAsset·GetModels는 기본 활성이지만 AI 생성 기능은 Unity Credits를 소모합니다.
Profiler 주의: Profiler 도구군은 Unity Profiler 창에 캡처된 데이터가 있어야 의미 있는 결과를 반환합니다.

전체 빠른 참조

도구 ID 그룹 기능 요약 기본 활성
Unity.ManageScript Core 레거시 스크립트 작업 라우터 (create/read/delete) ✗
Unity.ManageScript_capabilities Core ManageScript 지원 작업·제한 정보 조회 ✗
Unity.CreateScript Core 지정 경로에 C# 스크립트 신규 생성 ✗
Unity.DeleteScript Core URI 또는 경로로 C# 스크립트 삭제 ✗
Unity.GetSha Core 파일 SHA256 해시 및 메타데이터 조회 ✗
Unity.ApplyTextEdits Core 정확한 좌표 기반 파일 텍스트 편집 ✗
Unity.ScriptApplyEdits Core 메서드·클래스 단위 구조적 C# 편집 ✗
Unity.ValidateScript Core C# 스크립트 구문/성능 진단 ✗
Unity.RunCommand Core C# 코드를 Editor에서 즉시 컴파일·실행 ✓
Unity.ListResources Core 프로젝트 내 파일 URI 목록 조회 ✗
Unity.ReadResource Core 파일 내용 읽기 (슬라이싱 지원) ✗
Unity.FindInFile Core 파일 내 정규식 패턴 검색 ✗
Unity.ManageGameObject Core GameObject 생성·수정·삭제·컴포넌트 작업 ✗
Unity.ManageScene Core 씬 로드·저장·생성·계층 구조 조회 ✗
Unity.ManageEditor Core Editor 재생·일시정지·상태 제어 ✗
Unity.ManageMenuItem Core Editor 메뉴 항목 실행·검색 ✗
Unity.ManageAsset Core 에셋 임포트·생성·수정·삭제·검색 ✗
Unity.ImportExternalModel Core 외부 URL의 FBX를 임포트·씬 배치·프리팹 저장 ✗
Unity.ManageShader Assets 셰이더 스크립트 생성·읽기·수정·삭제 ✗
Unity.AssetGeneration.GenerateAsset Assets AI로 스프라이트·이미지·3D모델·사운드 생성 ✓
Unity.AssetGeneration.GetModels Assets 에셋 생성 가능 AI 모델 목록 조회 ✓
Unity.AssetGeneration.GetCompositionPatterns Assets 머티리얼·TerrainLayer 생성용 패턴 조회 ✗
Unity.AssetGeneration.ManageInterrupted Assets 중단된 에셋 생성 작업 확인·재개 ✗
Unity.AssetGeneration.ConvertToMaterial Assets 텍스처 → Material 변환 (비생성형) ✗
Unity.AssetGeneration.ConvertToTerrainLayer Assets 텍스처 → TerrainLayer 변환 (비생성형) ✗
Unity.AssetGeneration.ConvertSpriteSheetToAnimationClip Assets 스프라이트 시트 → AnimationClip 변환 ✗
Unity.AssetGeneration.CreateAnimatorControllerFromClip Assets AnimationClip → AnimatorController 생성 ✗
Unity.AssetGeneration.EditAnimationClipTool Assets 휴머노이드 AnimationClip 수정 ✗
Unity.AudioClip.Edit Assets 오디오 클립 무음 제거·트리밍·볼륨·루프 편집 ✗
Unity.FindProjectAssets Assets 이름 매칭 + 시각적 의미론적 에셋 검색 ✗
Unity.Grep Assistant ripgrep으로 파일 내용·경로 검색 ✗
Unity.ReadConsole Debug 콘솔 메시지 조회·필터·지우기 ✗
Unity.GetConsoleLogs Debug 스택 트레이스 포함 콘솔 로그 조회 ✓
Unity.Profiler.GetFrameRangeTopTimeSummary Debug 다중 프레임 구간 상위 시간 요약 ✗
Unity.Profiler.GetFrameTopTimeSamplesSummary Debug 특정 프레임 총 시간 기준 상위 샘플 요약 ✗
Unity.Profiler.GetFrameSelfTimeSamplesSummary Debug 특정 프레임 자체 시간 기준 상위 샘플 요약 ✗
Unity.Profiler.GetSampleTimeSummary Debug 특정 프로파일러 샘플 시간 요약 ✗
Unity.Profiler.GetBottomUpSampleTimeSummary Debug 바텀업 분석 기준 샘플 시간 요약 ✗
Unity.Profiler.GetSampleTimeSummaryByMarkerPath Debug Marker Id Path 기준 샘플 시간 요약 ✗
Unity.Profiler.GetRelatedSamplesTimeSummary Debug 동시 실행 타 스레드 관련 샘플 요약 ✗
Unity.Profiler.GetOverallGcAllocationsSummary Debug 전체 프로파일링 데이터 GC 할당 요약 ✗
Unity.Profiler.GetFrameGcAllocationsSummary Debug 특정 프레임 상위 GC 할당 샘플 요약 ✗
Unity.Profiler.GetFrameRangeGcAllocationsSummary Debug 다중 프레임 구간 GC 할당 요약 ✗
Unity.Profiler.GetSampleGcAllocationSummary Debug 특정 샘플 GC 할당 요약 ✗
Unity.GetUserGuidelines Editor 프로젝트 코딩 컨벤션·폴더 구조 컨텍스트 로드 ✗
Unity.GetProjectData Editor 프로젝트 개요 데이터 조회 ✗
Unity.PackageManager.GetPackageData Editor 패키지 정보 조회 ✗
Unity.PackageManager.PackageManagerExecuteAction Editor 패키지 추가·제거·샘플 설치 ✗
Unity.Camera.Capture Editor 특정 카메라 또는 씬 뷰 이미지 캡처 ✓
Unity.SceneView.Capture2DScene Editor 2D 씬 특정 영역 직교 투영 캡처 ✓
Unity.SceneView.CaptureMultiAngleSceneView Editor 3D 씬 4방향 멀티앵글 캡처 ✓

Core (18개)

[McpTool] 어트리뷰트로 직접 등록됩니다. 소스 경로: Modules/Unity.AI.MCP.Editor/Tools/

Unity.ManageScript

레거시 스크립트 작업 호환성 라우터입니다. 파일 직접 읽기에는 resources/read, 편집에는 Unity.ApplyTextEdits 또는 Unity.ScriptApplyEdits 사용을 권장합니다.

파라미터 타입 필수 기본값 설명
action 문자열 ✓ — 'create' | 'read' | 'delete'
name 문자열 ✓ — 스크립트 이름 (.cs 제외)
path 문자열 ✗ "Assets/" 에셋 경로
contents 문자열 ✗ — create/update 시 C# 코드
script_type 문자열 ✗ — 타입 힌트 (예: 'MonoBehaviour')
namespace 문자열 ✗ — 스크립트 네임스페이스

반환: { success, message, data }

Unity.ManageScript_capabilities

Unity.ManageScript의 지원 작업·제한·가드 설정 정보를 조회합니다.

파라미터 없음

반환: { ops, text_ops, max_edit_payload_bytes, guards }

Unity.CreateScript

지정 경로에 새 C# 스크립트를 생성합니다. 경로는 Assets/ 하위여야 하며, 전송 시 콘텐츠는 Base64로 인코딩됩니다.

파라미터 타입 필수 기본값 설명
path 문자열 ✓ — 에셋 경로 (예: 'Assets/Scripts/My.cs')
contents 문자열 ✓ — C# 코드
script_type 문자열 ✗ — 타입 힌트 (예: 'MonoBehaviour')
namespace 문자열 ✗ — 네임스페이스

Unity.DeleteScript

URI 또는 Assets 상대 경로로 C# 스크립트를 삭제합니다. 대상은 Assets/ 하위여야 합니다.

파라미터 타입 필수 기본값 설명
uri 문자열 ✓ — unity://path/... | file://... | Assets/...

Unity.GetSha

파일 내용을 반환하지 않고 SHA256 해시와 기본 메타데이터만 조회합니다. Unity.ApplyTextEdits의 precondition_sha256과 함께 사용하면 동시 편집 충돌을 방지할 수 있습니다.

파라미터 타입 필수 기본값 설명
uri 문자열 ✓ — 대상 파일 URI

반환: { sha256, metadata }

Unity.ApplyTextEdits

URI로 식별된 파일의 정확한 문자 위치를 교체합니다. 줄·열 번호는 모두 1부터 시작하며 탭은 1칸으로 계산합니다.

권장 워크플로: Unity.ReadResource → Unity.FindInFile → Unity.ApplyTextEdits

파라미터 타입 필수 기본값 설명
uri 문자열 ✓ — 편집할 파일 URI
edits 배열 ✓ — 편집 항목 목록. 각 항목: { startLine, startCol, endLine, endCol, newText }
precondition_sha256 문자열 ✗ — 현재 파일 SHA256. 동시 편집 충돌 방지용

Unity.ScriptApplyEdits

메서드·클래스 단위의 구조적 C# 편집입니다. 원시 텍스트 교체보다 안전하므로 우선 사용을 권장합니다.

파라미터 타입 필수 기본값 설명
op 문자열 ✓ — replace_method | insert_method | delete_method | anchor_insert | anchor_delete | anchor_replace
className 문자열 ✗ name 필드 대상 클래스명
methodName 문자열 조건부 — replace_method, delete_method 시 필수
replacement 문자열 조건부 — replace_method, insert_method 시 필수
position 문자열 ✗ — insert_method 전용: start | end | after | before
afterMethodName 문자열 조건부 — position='after' 시 필수
beforeMethodName 문자열 조건부 — position='before' 시 필수
anchor 문자열 조건부 — anchor_* 작업용 정규식
text 문자열 조건부 — anchor_insert, anchor_replace 시 삽입할 텍스트
options.validate 문자열 ✗ — 'standard' (구조 검사) | 'relaxed' (내부 전용 편집)

Unity.ValidateScript

C# 스크립트의 구문 오류 및 성능 힌트를 진단합니다.

파라미터 타입 필수 기본값 설명
uri 문자열 ✓ — 검증할 스크립트 URI
level 문자열 ✗ 'basic' 'basic' (빠른 구문 검사) | 'standard' (성능 힌트 포함)
include_diagnostics 불리언 ✗ false true이면 전체 진단 및 요약 반환

Unity.RunCommand ★ 기본 활성

Unity Editor에서 C# 코드를 즉시 컴파일하고 실행합니다. 물리·입력·그래픽·게임플레이·패키지 관리 등 Editor의 거의 모든 기능을 프로그래밍 방식으로 제어할 수 있습니다. 빌트인 도구 중 활용 범위가 가장 넓습니다.

파라미터 타입 필수 기본값 설명
code 문자열 ✓ — 실행할 C# 코드. 클래스명은 반드시 CommandScript여야 함
title 문자열 ✗ — 작업 제목 (로그 식별용)

반환: { compilationStatus, executionStatus, logs, results }

황금 템플릿 (이 형식에서 벗어나면 실행에 실패합니다):

internal class CommandScript
{
    [UnityEditor.MenuItem("Tools/RunCommand", false, 0)]
    public static void Execute()
    {
        var result = new System.Collections.Generic.Dictionary<string, object>();
        // 코드 작성 위치
        UnityEngine.Debug.Log(Newtonsoft.Json.JsonConvert.SerializeObject(result));
    }
}

Unity.ListResources

지정 폴더 하위의 파일 URI 목록을 반환합니다.

파라미터 타입 필수 기본값 설명
Pattern 문자열 ✗ "*" 파일 필터링용 Glob 패턴
Under 문자열 ✗ "Assets" 검색할 루트 하위 폴더
Limit 정수 ✗ 200 최대 반환 개수
ProjectRoot 문자열 ✗ — 프로젝트 루트 경로 재정의

반환: { success, data: { uris, count }, error? }

Unity.ReadResource

unity://path/... URI로 파일 내용을 읽습니다. 줄·바이트 단위 슬라이싱을 지원합니다.

파라미터 타입 필수 기본값 설명
Uri 문자열 ✓ — 읽을 파일 URI (Assets/ 하위)
StartLine 정수 ✗ — 시작 줄 번호 (1부터)
LineCount 정수 ✗ — 읽을 줄 수
HeadBytes 정수 ✗ — 파일 시작부터 읽을 바이트 수
TailLines 정수 ✗ — 파일 끝에서 읽을 줄 수
Request 문자열 ✗ — 자연어 요청 (예: '마지막 120줄', 'MethodName 주변 40줄')
ProjectRoot 문자열 ✗ — 프로젝트 루트 경로 재정의

반환: { success, data: { text, metadata }, error? }

Unity.FindInFile

정규식 패턴으로 파일 내부를 검색하고 줄 번호와 발췌문을 반환합니다. 이름 변경·편집 대상 위치를 잡을 때 유용합니다.

파라미터 타입 필수 기본값 설명
Uri 문자열 ✓ — 검색할 파일 URI
Pattern 문자열 ✓ — 정규식 검색 패턴
IgnoreCase 불리언 ✗ true 대소문자 무시 여부
MaxResults 정수 ✗ 200 최대 반환 결과 수
ProjectRoot 문자열 ✗ — 프로젝트 루트 경로 재정의

반환: { success, data: { matches, count }, error? }

Unity.ManageGameObject

GameObject를 생성·수정·삭제·검색하고 컴포넌트 작업을 수행합니다.

파라미터 타입 필수 기본값 설명
action 문자열 ✓ — 'create' | 'modify' | 'find' | 'add_component' | 'remove_component' | 'set_component_property' | 'get_components' | 'get_component'
target 문자열 조건부 — GameObject 이름 또는 계층 경로. modify/delete/컴포넌트 작업 시 필수
properties 객체 ✗ — create/modify 시 속성 (position, rotation, scale, parent 등)
component_type 문자열 조건부 — 컴포넌트 작업 시 타입명 (예: 'Rigidbody')
component_properties 객체 조건부 — set_component_property 시 { 속성명: 값 }
search_inactive 불리언 ✗ false find 시 비활성 GameObject 포함 여부

반환: { success, message, data }

Unity.ManageScene

Unity 씬을 로드·저장·생성하거나 계층 구조를 조회합니다.

파라미터 타입 필수 기본값 설명
Action 문자열 ✓ — 'Load' | 'Save' | 'Create' | 'GetHierarchy' (외 다수)
Name 문자열 조건부 — create/load/save 대상 씬 이름 (확장자 제외)
Path 문자열 ✗ "Assets/" 씬 에셋 경로
BuildIndex 정수 ✗ — load/빌드 설정 작업용 빌드 인덱스

반환: { success, message, data }

Unity.ManageEditor

Unity Editor의 재생 상태·활성 도구·태그·레이어 등을 제어하고 조회합니다.

파라미터 타입 필수 기본값 설명
Action 문자열 ✓ — 'Play' | 'Pause' | 'Stop' | 'GetState' | 'SetActiveTool' | 'AddTag' | 'AddLayer' (외 다수)
WaitForCompletion 불리언 ✗ — true이면 일부 작업 완료까지 대기
ToolName 문자열 조건부 — SetActiveTool 시 도구명
TagName 문자열 조건부 — AddTag 시 태그명
LayerName 문자열 조건부 — AddLayer 시 레이어명

반환: { success, message, data }

Unity.ManageMenuItem

Unity Editor 메뉴 항목을 실행·검색·존재 확인합니다. 메뉴 경로를 모를 때는 'List'로 먼저 탐색하세요.

파라미터 타입 필수 기본값 설명
Action 문자열 ✓ — 'Execute' | 'List' | 'Exists' | 'Refresh'
MenuPath 문자열 조건부 — Execute/Exists 시 필수 (예: 'File/Save Project')
Search 문자열 ✗ — List 시 대소문자 무시 필터 문자열
Refresh 불리언 ✗ — 작업 전 메뉴 캐시 강제 새로고침

반환: { success, message, data }

Unity.ManageAsset

에셋 임포트·생성·수정·삭제·이동·검색 등 광범위한 에셋 작업을 수행합니다.

파라미터 타입 필수 기본값 설명
Action 문자열 ✓ — 'Import' | 'Create' | 'Modify' | 'Delete' | 'Duplicate' | 'Move' | 'Rename' | 'Search' | 'GetInfo' | 'CreateFolder' | 'GetComponents'
Path 문자열 조건부 — 에셋 경로 또는 검색 범위
AssetType 문자열 조건부 — Create 시 필수 (예: 'Material', 'Folder')
Properties 객체 ✗ — Create/Modify 시 속성 딕셔너리
Destination 문자열 조건부 — Duplicate/Move 시 대상 경로
SearchPattern 문자열 ✗ — 검색 패턴 (예: '*.prefab')
Page 정수 ✗ — 검색 결과 페이지네이션

반환: { success, data, error }

Unity.ImportExternalModel

URL에서 FBX를 다운로드해 프로젝트에 임포트하고, 씬에 배치한 뒤 프리팹으로 저장합니다.

파라미터 타입 필수 기본값 설명
name 문자열 ✓ — 에셋 이름 (단일 단어/ID, 공백 불가)
fbx_url 문자열 ✓ — FBX 파일 URL (로컬 파일, URL, FBX 포함 zip 모두 가능)
height 실수 ✗ — 씬에서의 원하는 높이
albedo_texture_url 문자열 ✗ — 알베도 텍스처 파일 URL

반환: { success, data: { sceneGameObject, prefab }, error }

Assets (12개)

Unity.ManageShader는 [McpTool] 직접 등록, 나머지 11개는 AgentToolMcpAdapter를 통해 브리징됩니다.

Unity.ManageShader

셰이더 스크립트를 CRUD 방식으로 관리합니다.

파라미터 타입 필수 기본값 설명
Action 문자열 ✓ — 'Create' | 'Read' | 'Update' | 'Delete'
Name 문자열 ✓ — 셰이더 이름 (.shader 확장자 제외)
Path 문자열 ✗ "Assets/" 에셋 경로
Contents 문자열 조건부 — Create/Update 시 셰이더 코드

반환: { success, message, data }

Unity.AssetGeneration.GenerateAsset ★ 기본 활성

command 파라미터 하나로 스프라이트·이미지·3D 모델·사운드·머티리얼 등 다양한 에셋을 AI로 생성합니다. Unity Credits를 소모합니다.

파라미터 타입 필수 기본값 설명
command 문자열 ✓ — 아래 지원 명령 목록 참조
modelId 문자열 조건부 — 생성 명령 시 필수. GetModels로 유효 ID 확인
prompt 문자열 조건부 — 생성 내용 설명. 음성 생성 시에는 발화 텍스트만 입력
targetAssetPath 문자열 조건부 — 편집·업스케일·변환 명령 시 대상 에셋 경로
referenceImageInstanceId 문자열 ✗ — 재채색 시 색상 팔레트 이미지 ID
referenceImageInstanceIds 배열 ✗ — 멀티뷰 3D 모델 생성 시 참조 이미지 ID 목록
referenceImageLabels 배열 ✗ — 멀티뷰 이미지 뷰 레이블 (예: ['front', 'back', 'left'])
voiceName 문자열 ✗ — 음성 생성 시 보이스 선택
durationInSeconds 정수 ✗ — 사운드 길이 (1~10초)
loop 불리언 ✗ — 끊김 없는 루프 생성 여부

지원 command 목록:

command 설명
GenerateSprite 스프라이트 생성 (이후 RemoveImageBackground 호출 권장)
GenerateImage 이미지 생성 (초상화, 배경 등)
RemoveImageBackground 기존 스프라이트/이미지 배경 제거
UpscaleImage / UpscaleSprite 이미지/스프라이트 업스케일
RecolorImage / RecolorSprite 색상 팔레트 이미지 기준 재채색
EditSpriteWithPrompt / EditImageWithPrompt 프롬프트로 스프라이트/이미지 편집
GenerateSpritesheet 프롬프트로 스프라이트 시트 생성
GenerateCubemap / UpscaleCubemap 큐브맵 생성/업스케일
GenerateMaterial / AddPbrToMaterial 머티리얼 생성 / PBR 맵 추가
GenerateTerrainLayer / AddPbrToTerrainLayer TerrainLayer 생성 / PBR 맵 추가
GenerateSound 효과음 또는 음성 생성
GenerateMesh 3D 모델(프리팹) 생성
RetopologyMesh 기존 메시 리토폴로지
TextureMesh 기존 메시에 텍스처 추가
RigMesh 기존 메시에 리깅 추가

Unity.AssetGeneration.GetModels ★ 기본 활성

에셋 생성에 사용 가능한 AI 모델 목록을 조회합니다. GenerateAsset 호출 전 modelId 확인에 사용합니다.

파라미터 없음

반환: 모델 목록 (각 항목에 ModelId guid 포함)

Unity.AssetGeneration.GetCompositionPatterns

머티리얼·TerrainLayer 생성 시 참조 이미지로 쓸 수 있는 컴포지션 패턴 목록을 조회합니다. GenerateMaterial/GenerateTerrainLayer 호출 전에 먼저 조회해 두는 편이 안전합니다.

파라미터 없음

Unity.AssetGeneration.ManageInterrupted

중단된 에셋 생성 작업을 확인하거나 재개합니다.

파라미터 상세는 소스에서 확인하지 못했습니다.

Unity.AssetGeneration.ConvertToMaterial

기존 Texture2D 또는 Cubemap 에셋으로 Material을 생성합니다. 생성형 AI를 사용하지 않습니다.

파라미터 타입 필수 기본값 설명
targetAssetPath 문자열 ✓ — Texture2D 또는 Cubemap 에셋 경로
savePath 문자열 ✓ — 생성할 .mat 파일 저장 경로

Unity.AssetGeneration.ConvertToTerrainLayer

기존 Texture2D 에셋으로 TerrainLayer를 생성합니다. 생성형 AI를 사용하지 않습니다.

파라미터 타입 필수 기본값 설명
referenceImagePath 문자열 ✓ — Texture2D 에셋 경로
savePath 문자열 ✓ — 생성할 .terrainlayer 파일 저장 경로

Unity.AssetGeneration.ConvertSpriteSheetToAnimationClip

미리 슬라이스된 Texture2D 스프라이트 시트로 AnimationClip을 생성합니다.

파라미터 타입 필수 기본값 설명
referenceImagePath 문자열 ✓ — 슬라이스된 Texture2D 에셋 경로
savePath 문자열 ✓ — 생성할 .anim 파일 저장 경로

Unity.AssetGeneration.CreateAnimatorControllerFromClip

기존 AnimationClip으로 AnimatorController를 생성하고 해당 클립을 기본 상태로 설정합니다.

파라미터 타입 필수 기본값 설명
animationClipPath 문자열 ✓ — 기존 .anim 에셋 경로
savePath 문자열 ✓ — 생성할 .controller 파일 저장 경로

Unity.AssetGeneration.EditAnimationClipTool

Unity 휴머노이드 AnimationClip을 편집합니다. 휴머노이드 클립만 지원합니다.

파라미터 타입 필수 기본값 설명
command 문자열 ✓ — 'MakeStationary' (루트 모션 제거) | 'TrimToBestLoop' (최적 루프 구간 트리밍)
targetAssetPath 문자열 ✓ — 대상 .anim 파일 경로

Unity.AudioClip.Edit

AudioClip 에셋의 무음 제거·트리밍·볼륨 조정·루프 생성을 수행합니다. LoopSound 전에 TrimSilence로 무음을 먼저 제거하면 더 자연스러운 루프를 얻을 수 있습니다.

파라미터 타입 필수 기본값 설명
command 문자열 ✓ — 'TrimSilence' | 'TrimSound' | 'ChangeVolume' | 'LoopSound'
targetAssetPath 문자열 ✓ — 대상 Audio Clip 에셋 경로
startTime 실수 조건부 — TrimSound 시 트리밍 시작 시간 (초)
endTime 실수 조건부 — TrimSound 시 트리밍 종료 시간 (초)
volume 실수 조건부 — ChangeVolume 시 볼륨 값

Unity.FindProjectAssets

이름 매칭과 시각적 의미론적 검색을 결합해 프로젝트 에셋을 검색합니다.

파라미터 타입 필수 기본값 설명
query 문자열 ✓ — 검색 쿼리. 아래 접두사 구문 지원

쿼리 접두사 구문:

접두사 의미 예시
t:<type> 에셋 타입 필터 t:Texture2D, t:Prefab
dir:<path> 검색 디렉토리 제한 dir:Assets/Characters
l:<label> 에셋 레이블 필터 l:Environment
k:<keyword> 키워드 검색 k:fire particle

반환 결과에는 ResponseGuidance 필드가 포함되며, 결과 표시 시 해당 지침을 따라야 합니다.

Assistant (1개)

Unity.Grep

ripgrep(rg)으로 프로젝트 파일 내용을 검색하거나 경로 패턴으로 파일을 나열합니다. 기본적으로 .cs 파일만 검색합니다.

파라미터 타입 필수 기본값 설명
args 문자열 ✓ — ripgrep 인자 문자열. 검색 패턴 포함. --glob/--type으로 파일 타입 지정, -l로 파일 경로만 출력
path 문자열 ✗ — 검색 범위 디렉토리 (지정 시 해당 폴더로 제한)

사용 예시:
– 전체 .cs에서 NavMeshAgent 검색: args="NavMeshAgent"
– JSON 파일에서 검색: args="--type json \"someKey\""
– 파일 목록만 출력: args="-l \"TODO\""

Debug & Diagnostics (14개)

Unity.ReadConsole은 [McpTool] 직접 등록, Unity.GetConsoleLogs와 Profiler 도구 11개는 AgentToolMcpAdapter 브리징입니다.

Profiler 사전 조건: Profiler 도구군은 Unity Profiler 창에 캡처된 데이터가 있어야 동작합니다. 데이터 없이 호출하면 빈 결과를 반환합니다.

Unity.ReadConsole

Unity Editor 콘솔 메시지를 조회하거나 콘솔을 지웁니다. Unity.GetConsoleLogs보다 세밀한 필터링(타입·시간·형식)을 지원합니다.

파라미터 타입 필수 기본값 설명
Action 문자열 ✓ — 'Get' | 'Clear'
Types 문자열 ✗ 'All' 'Error' | 'Warning' | 'Log' | 'All'
Count 정수 ✗ — 최대 반환 메시지 수
FilterText 문자열 ✗ — 메시지 텍스트 필터
SinceTimestamp 문자열 ✗ — 해당 시점 이후 메시지만 조회 (ISO 8601)
Format 문자열 ✗ 'Plain' 'Plain' | 'Detailed' | 'Json'
IncludeStacktrace 불리언 ✗ — 스택 트레이스 포함 여부

반환: { success, data: { messages } }

Unity.GetConsoleLogs ★ 기본 활성

스택 트레이스를 포함한 Unity 콘솔 로그를 간편하게 조회합니다. 빠른 디버깅에는 이 도구가, 세밀한 필터링이 필요할 때는 Unity.ReadConsole이 적합합니다.

파라미터 타입 필수 기본값 설명
maxEntries 정수 ✗ 50 최대 항목 수
includeStackTrace 불리언 ✗ true 스택 트레이스 포함 여부
logTypes 문자열 ✗ "info,warning,error" 조회할 로그 타입 (쉼표 구분)

Profiler 도구 (11개)

Profiler 도구는 모두 ProfilingSummaryTools.cs에서 McpAvailability.Available로 등록됩니다. 각 도구의 파라미터 상세는 소스 코드에서 직접 확인해야 합니다 — 이 섹션만큼은 소스를 완전히 파싱하지 못했습니다.

도구 ID 주요 입력 설명
Unity.Profiler.GetFrameRangeTopTimeSummary 프레임 범위 다중 프레임 구간 상위 시간 요약
Unity.Profiler.GetFrameTopTimeSamplesSummary 프레임 번호 특정 프레임 총 시간 기준 상위 샘플
Unity.Profiler.GetFrameSelfTimeSamplesSummary 프레임 번호 특정 프레임 자체 시간 기준 상위 샘플
Unity.Profiler.GetSampleTimeSummary 샘플 식별자 특정 샘플 시간 요약
Unity.Profiler.GetBottomUpSampleTimeSummary 샘플 식별자 바텀업 분석 기준 샘플 시간
Unity.Profiler.GetSampleTimeSummaryByMarkerPath Marker Id Path Marker 경로 기준 샘플 시간
Unity.Profiler.GetRelatedSamplesTimeSummary 샘플 식별자 동시 실행 타 스레드 관련 샘플
Unity.Profiler.GetOverallGcAllocationsSummary (없음) 전체 데이터 GC 할당 요약
Unity.Profiler.GetFrameGcAllocationsSummary 프레임 번호 특정 프레임 상위 GC 할당 샘플
Unity.Profiler.GetFrameRangeGcAllocationsSummary 프레임 범위 다중 프레임 구간 GC 할당 요약
Unity.Profiler.GetSampleGcAllocationSummary 샘플 식별자 특정 샘플 GC 할당 요약

Editor (7개)

모두 AgentToolMcpAdapter를 통해 브리징됩니다.

Unity.GetUserGuidelines

프로젝트의 코딩 컨벤션·폴더 구조·네이밍 규칙 등 컨텍스트를 로드합니다. 파일 생성·편집·분석 전에 호출하면 기존 프로젝트 스타일에 맞는 결과를 얻을 수 있습니다.

파라미터 없음

Unity.GetProjectData

프로젝트 개요 마크다운 생성에 필요한 기본 프로젝트 데이터를 반환합니다.

파라미터 없음

Unity.PackageManager.GetPackageData

Unity 패키지의 설명·버전·의존성 정보를 조회합니다. 패키지 설치에는 사용할 수 없습니다.

파라미터 타입 필수 기본값 설명
packageName 문자열 ✓ — 패키지 이름 (예: com.unity.addressables)

※ 파라미터명은 소스에서 직접 확인하지 못해 실제 이름과 다를 수 있습니다.

Unity.PackageManager.PackageManagerExecuteAction

Unity 패키지를 추가·제거하거나 샘플을 설치합니다.

파라미터 타입 필수 기본값 설명
action 문자열 ✓ — 'Add' | 'Remove' | 'InstallSample' (추정)
packageName 문자열 ✓ — 패키지 이름

※ 파라미터명은 소스에서 직접 확인하지 못해 실제 이름과 다를 수 있습니다.

Unity.Camera.Capture ★ 기본 활성

씬의 특정 카메라 또는 현재 씬 뷰를 이미지로 캡처합니다. 연산 비용이 높으므로 씬 뷰 컨텍스트가 반드시 필요한 경우에만 사용하세요.

파라미터 타입 필수 기본값 설명
instanceId 정수 ✗ — Camera 컴포넌트를 가진 GameObject의 인스턴스 ID. 생략 시 현재 씬 뷰 캡처

Unity.SceneView.Capture2DScene ★ 기본 활성

2D 씬의 특정 직사각형 영역을 직교 투영(탑다운)으로 캡처합니다.

파라미터 타입 필수 기본값 설명
x 실수 ✓ — 캡처 영역 중심 월드 X 좌표
y 실수 ✓ — 캡처 영역 중심 월드 Y 좌표
width 실수 ✓ — 캡처 영역 월드 너비
height 실수 ✓ — 캡처 영역 월드 높이
pixelsPerUnit 실수 ✗ — 해상도 (높을수록 상세하지만 이미지 크기 증가)

Unity.SceneView.CaptureMultiAngleSceneView ★ 기본 활성

3D 씬을 아이소메트릭·정면·상단·우측 4방향으로 캡처해 2×2 그리드로 반환합니다. 3D 씬 전용이며, 2D 씬에는 Unity.SceneView.Capture2DScene을 사용하세요.

파라미터 타입 필수 기본값 설명
focusObjectIds 정수 배열 ✗ — 프레임을 맞출 GameObject 인스턴스 ID 목록. 생략 시 씬 전체 오브젝트 프레임

실제로 자주 쓰이는 조합

레퍼런스를 한 번 훑고 나면 어떤 도구를 조합해 쓸지 감이 잡힐 겁니다. 실무에서 반복되는 패턴 몇 가지를 짚어둡니다.

스크립트 편집 흐름: Unity.GetSha → Unity.ReadResource → Unity.FindInFile → Unity.ApplyTextEdits 순서가 안전합니다. SHA를 미리 잡아두면 동시 편집 충돌을 막을 수 있습니다. 구조적 변경이라면 Unity.ScriptApplyEdits를 먼저 고려하세요.

AI 에셋 생성 흐름: Unity.AssetGeneration.GetModels로 유효한 modelId를 확인한 뒤 GenerateAsset을 호출하는 것이 기본입니다. 스프라이트라면 생성 직후 RemoveImageBackground를 이어서 호출하는 것이 Unity 공식 소스에서도 권장하는 순서입니다.

Profiler 분석 흐름: Unity Profiler 창에 캡처 데이터가 없으면 Profiler 도구 11개는 전부 빈 결과를 돌려줍니다. 데이터를 먼저 캡처한 뒤, GetFrameRangeTopTimeSummary로 병목 구간을 좁히고 GetSampleTimeSummary로 특정 샘플을 파고드는 순서가 효율적입니다.

함께 읽으면 좋은 포스팅

← 이전 편: 4편 — Unity Skills 시스템으로 AI 워크플로우 자동화하기

댓글 남기기

© 2026 GameDevLLM.com · All Rights Reserved