unity-mcp — Unity Editor MCP 연동 스킬
When to use this skill
-
Unity3D 프로젝트에서 AI 에이전트로 씬·스크립트·에셋 작업을 자동화할 때
-
omu, bmad-gds 워크플로우에서 Unity Editor를 직접 제어할 때
-
C# 스크립트 생성·검증·적용을 AI에게 위임할 때
-
Unity Test Runner 자동 실행 및 콘솔 로그 분석이 필요할 때
설치 및 초기 설정
Step 1 — Unity Package 설치
Unity Editor → Window → Package Manager → "+" → Add from git URL:
https://github.com/CoplayDev/unity-mcp.git
Step 2 — Unity MCP 서버 시작
Unity Editor → Window → MCP → Start
서버 동작 확인
curl http://localhost:8080/health
→ {"status":"healthy","version":"..."}
Step 3 — AI 클라이언트 MCP 자동 설정 (AI가 실행)
AI 에이전트에게: 사용자가 unity-mcp 설정을 요청하면 아래 절차를 자동으로 실행하세요.
Claude Code (~/.claude/settings.json )
AI 실행 절차:
1. ~/.claude/settings.json 읽기
2. mcpServers.unity 항목을 URL 방식으로 추가/교체
3. 파일 저장 후 사용자에게 Claude Code 재시작 안내
설정 값:
{ "mcpServers": { "unity": { "url": "http://localhost:8080/mcp" } } }
Codex CLI (~/.codex/config.toml )
[[mcp_servers]] name = "unity" url = "http://localhost:8080/mcp"
Gemini CLI (~/.gemini/settings.json )
{ "mcpServers": { "unity": { "url": "http://localhost:8080/mcp" } } }
동작 원리: mcp-for-unity 는 Unity Editor가 직접 실행하는 HTTP 서버입니다. AI 클라이언트는 새 프로세스를 띄우지 않고, URL로 이미 실행 중인 서버에 연결합니다.
⚠️ "command": "python" 방식(subprocess)은 포트 충돌로 동작하지 않습니다.
Step 4 — 도구 확인
Claude Code 재시작 후:
/mcp # unity 항목과 도구 목록 확인
역할별 도구 매핑
PM 맥락 (기획·스프린트 관리)
도구 활용 시나리오 연동 스킬
project_info (resource) 프로젝트 현황 → 스프린트 계획 bmad-gds (bmad-gds-sprint-planning)
get_tests
테스트 커버리지 → 릴리즈 체크리스트 bmad-gds (bmad-gds-sprint-status)
editor_state
씬/빌드 상태 → 데모 준비 확인 task-planning
read_console
버그 리포트 수집 → 스토리 생성 log-analysis, bmad-gds
디자이너 맥락 (UI/UX·비주얼)
도구 활용 시나리오 연동 스킬
manage_ui
UI 컴포넌트 계층 생성/수정 design-system, ui-component-patterns
manage_material , manage_shader
시각 스타일 프로토타이핑 design-system
manage_vfx , manage_animation
모션/이펙트 빠른 이터레이션 bmad-gds (bmad-gds-quick-prototype)
manage_probuilder
레벨 레이아웃 그레이박싱 bmad-gds (bmad-gds-gdd)
manage_texture
에셋 임포트 설정 file-organization
게임개발자 맥락 (구현·테스트·최적화)
도구 활용 시나리오 연동 스킬
create_script , validate_script
C# 생성 + Roslyn 검증 bmad-gds (bmad-gds-dev-story)
script_apply_edits , manage_script
코드 수정·리팩터링 code-refactoring
manage_gameobject , manage_components
씬 오브젝트 조작 bmad-gds (bmad-gds-quick-dev)
run_tests , get_test_job
Unity Test Runner 자동 실행 testing-strategies
read_console
런타임 에러 수집 log-analysis
find_gameobjects , find_in_file
디버깅 중 대상 탐색 codebase-search
batch_execute
반복 작업 10~100x 가속 workflow-automation
manage_prefabs , manage_asset
에셋 파이프라인 자동화 file-organization
전체 도구 목록 (37개)
씬·오브젝트
manage_scene · manage_gameobject · find_gameobjects · manage_prefabs · manage_components
스크립트
create_script · delete_script · manage_script · script_apply_edits · validate_script · manage_script_capabilities
에셋·비주얼
manage_asset · manage_material · manage_texture · manage_shader · manage_ui · manage_vfx · manage_animation · manage_probuilder · manage_scriptable_object
편집기 제어
manage_editor · execute_menu_item · manage_tools · refresh_unity · set_active_instance
워크플로우
batch_execute · apply_text_edits · find_in_file · execute_custom_tool
테스트·디버깅
run_tests · read_console · get_test_job · debug_request_context · get_sha
빠른 시작 (Quick Start)
1. Unity Editor에서 unity-mcp 서버 시작 (Unity MCP 창에서 Start 버튼)
2. 연결 확인
curl http://localhost:8080/health
3. omu 워크플로우에서 사용
omu "씬 프로토타이핑: 플랫포머 게임"
→ unity-mcp 도구가 자동으로 호출됨
관련 스킬
-
omu: 전체 오케스트레이션 (PLAN → EXECUTE → VERIFY → CLEANUP)
-
bmad-gds: 게임 개발 워크플로우 (기획 → 구현 → 리뷰)
-
design-system: UI 디자인 토큰 및 Unity3D Design Guide
-
log-analysis: read_console 출력 분석
-
performance-optimization: 게임 최적화 전략
-
testing-strategies: Unity Test Runner 전략
문제 해결
문제 해결 방법
/mcp 에 unity 도구가 안 보임 "command" 대신 "url": "http://localhost:8080/mcp" 사용 확인
localhost:8080 연결 안 됨 Unity Editor → MCP 창 → Start 버튼 클릭
스크립트 검증 실패 validate_script 에러 메시지 확인 후 manage_script 로 수정
batch_execute 타임아웃 작업을 소규모 배치로 분할
씬 로드 에러 read_console 로 에러 확인 → manage_scene 재시도
참고
-
unity-mcp GitHub — 37개 도구, 32개 리소스
-
Unity 2021.3 LTS+ 필요
-
MIT 라이선스 (오픈소스)