9.2 KiB

Raw Blame History

Unity MCP 연동 가이드 v2 (BurningTimes — 실전 검증 개정)

목적: BT 조직 개발자가 Unity MCP를 처음 연동·재설치할 때 따를 실전 검증 절차. 2026-04-21~22 BT3 도입 시 실제 겪은 이슈·해결안 반영.

대상: 개발팀·기획팀 (Unity Editor 조작에 MCP 도구 활용 전원)

개정 이력:

v1 (2026-04-21): HTTP 방식 기반 초안

v2 (2026-04-22): 실전 검증 — HTTP 거부·uvx 캐시 락·Transport 스위칭·Configure 자동화 반영

참조 규칙: C6-1 원본 보호 · C30 git 동기화 · C34-11 Agent 경계 · C11 개발 관점

1. 구성 개요

구성	역할
CoplayDev MCP for Unity (v9.6.x+)	Python 기반 MCP 서버 + Unity 에디터 패키지 2종
uv / uvx (Astral)	Python 패키지·MCP 서버 실행 환경
Claude Desktop	MCP 클라이언트 (BT 조직 기본 환경)
EerieVillage Unity 프로젝트	MCP 대상 Unity 프로젝트

🔴 중요 — Claude Desktop은 stdio 방식 전용

Claude Desktop은 공식적으로 HTTP MCP 서버 연결을 지원하지 않음. 실증: {"url": "http://..."} 방식은 "유효한 MCP 서버 구성이 아님" 경고로 거부됨. 반드시 stdio(uvx) 방식 사용.

통신 구조

Claude Desktop  ←stdio(uvx)→  mcpforunityserver (Python)  ←HTTP/WebSocket→  Unity Editor (MCP for Unity Package)

Claude Desktop → Python 서버: stdio(uvx) 전용
Python 서버 → Unity Editor: Unity Package가 Transport를 HTTP·stdio 둘 다 지원. Claude Desktop 대상 시 Unity 쪽 Transport도 stdio로 설정 필수 (Configure 시 자동 검증 경고)

2. 사전 요구 사항

Python 3.10+
uv (Astral 배포) — winget 권장
Unity 2021.3 LTS+ (EerieVillage는 6000.3.13f1 LTS)
BT 레포 clone + setup 스크립트 실행 (unity-mcp 자동 clone 포함)
Git 명령줄

3. 설치 절차 (신규 PC 기준 표준 7단계)

3-A. BT 레포 셋업

# Windows
git clone https://burning.i234.me/NerdNavis_AiDev/BurningTimesAi.git "E:/BurningTimes"
cd E:/BurningTimes
cp paths.local.json.template paths.local.json
# paths.local.json 편집:
#   UNITY_PROJECT_ROOT = 실제 Unity 프로젝트 경로 (ProjectSettings 폴더 있는 경로)
#   FRAMEWORK_PKG_ROOT = BT.Framework 경로 (선택)
#   DISCORD_WEBHOOK = BT 공용 웹훅 URL
.\setup\setup_windows.ps1

→ setup 스크립트가 코어코드/unity-mcp/에 CoplayDev 저장소를 자동 git clone.

3-B. uv 설치

# Windows (winget 권장)
winget install --id=astral-sh.uv -e --accept-source-agreements --accept-package-agreements

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

설치 후 터미널 재시작 (PATH 반영).

3-C. uvx 경로 확인

Get-Command uvx | Select-Object Source

보통 경로: C:\Users\{USERNAME}\AppData\Local\Microsoft\WinGet\Packages\astral-sh.uv_*\uvx.exe

3-D. uv 캐시 사전 워밍업 (중요 — pywin32 락 이슈 회피)

& "C:\Users\{USERNAME}\AppData\Local\Microsoft\WinGet\Packages\astral-sh.uv_Microsoft.Winget.Source_8wekyb3d8bbwe\uvx.exe" --from mcpforunityserver mcp-for-unity --help

3~5분 소요. --help 출력이 뜨면 성공 (의존성 pywin32·fastmcp·pydantic 등 캐시 구축 완료). 이 단계 건너뛰면 Claude Desktop 자동 시동 때 "pywin32.data 디렉토리 락" 에러로 disconnected 반복.

에러 시 대처:

Defender 예외 등록 (관리자 PowerShell):

Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\uv\cache"

캐시 삭제 후 재시도:

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\uv\cache" -ErrorAction SilentlyContinue

3-E. Unity Editor + MCP for Unity Package 설치

Unity Hub → EerieVillage 프로젝트 열기
Window → Package Manager → + → Install package from git URL...

입력:

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

설치·컴파일 완료 대기 (우하단 스피너 멈춤)

3-F. Unity MCP for Unity 창 설정 (v2 핵심)

Unity 상단 메뉴: Window → MCP for Unity 창 열기

① Transport를 stdio로 변경 (필수)

기본값은 HTTP Local — Claude Desktop 대상 시 그대로 Configure 누르면 "Claude Desktop does not support HTTP transport" 에러
Transport 드롭다운 → stdio 선택

② Server 구동

"Start Server" 버튼 → 🟢 Running 상태 확인

③ Client = Claude Desktop 선택

Client Configuration 드롭다운에서 "Claude Desktop" 선택

④ Configure 버튼 클릭 (자동 설정)

Unity가 %APPDATA%\Claude\claude_desktop_config.json을 자동으로 올바른 stdio 포맷으로 덮어씀
uvx 절대 경로·args 자동 탐지·기록
기존 수동 설정보다 안정적

3-G. Claude Desktop 완전 재시작 + 검증

트레이 아이콘 우클릭 → Quit (창 X는 트레이 잔류 — 미반영)
Claude Desktop 재실행
Claude 세션에서 요청: "Unity Console 로그 읽어줘"
제가 mcp__unityMCP__read_console 호출 → Unity Console 로그 실수신 확인

실증 (2026-04-22): 위 순서로 진행하면 5단계 만에 연동 성공. success: true + Unity Console 로그 배열 수신.

4. BT 조직 Unity MCP 편집 표준 워크플로우 v2

v1 계승 근거: 공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md §Unity MCP 편집 6단계 표준 워크플로우

편집 6단계 표준 (씬·프리팹·ScriptableObject·스크립트 편집 시)

단계	액션	근거 규칙
1. SHA 기록	Unity 프로젝트 `git rev-parse HEAD` 기록 (편집 전 커밋 확정)	C30 git 동기화
2. Read 선행	MCP 도구 또는 파일 직접 Read로 편집 전 상태 전수 파악	C5 정직성
3. 백업	원본 파일 `.bak_{YYYYMMDD_HHMM}.{ext}` 복사	C6-1 원본 보호
4. Unity 프로젝트 commit	편집 전 현 상태 Unity 레포 commit (롤백 지점)	C6-2 프로덕션 보호
5. 편집 집행	MCP 도구 호출. 상대 경로·`$UNITY_PROJECT_ROOT` 사용	C34-11 Agent 경계
6. 검증	Unity Console 오류 0건·의도 결과 반영 → 커밋	P14 QA 게이트

금지 행위

절대 경로 하드코딩 (PC별 달라지는 경로)
백업 없이 씬·프리팹 직접 편집
Unity Console 오류 잔존 상태로 작업 종료
MCP 응답 "완료" 신뢰하고 Unity Editor 실체 미검증

5. 트러블슈팅 — 실전 검증 이슈 7종

증상	원인	해결
`{"url": "..."}` 설정 시 "유효한 MCP 서버 구성이 아닙니다"	Claude Desktop HTTP 미지원	stdio(uvx) 방식으로 전환
"Could not attach to MCP server" 다수 서버 동시	Claude Desktop 좀비 인스턴스가 MCP 프로세스 락	작업관리자에서 `Claude.exe`·`uvx.exe`·`uv.exe`·`python.exe`·`node.exe` 전수 종료 후 재실행
"Server disconnected" 반복 (unityMCP)	uvx 첫 설치 시 `pywin32.data` 폴더 락 (Defender 실시간 검사·이전 프로세스)	3-D 수동 사전 워밍업 + 필요 시 Defender 예외 + `uv cache clean`
"MCP memory: Server disconnected" 또는 유사	다른 PC에서 가져온 config의 경로(`C:\Users\silve\...`) 무효	해당 PC 실제 경로로 수정 또는 불필요하면 제거
Unity Package 설치 후에도 "No Unity Editor instances found"	MCP for Unity 브릿지 서버 미구동	Unity → `Window → MCP for Unity` 창에서 "Start Server" 클릭
Configure 버튼 클릭 시 "Claude Desktop does not support HTTP transport"	Unity 쪽 Transport가 `HTTP Local` (기본값)	Transport 드롭다운 → `stdio` 선택 후 재Configure
Claude Desktop 재시작해도 변경 미반영	트레이 좀비 인스턴스 잔류 (창 X 닫기는 미종료)	트레이 아이콘 우클릭 Quit 또는 작업관리자 전수 종료

6. 업데이트·유지보수

unity-mcp 업스트림 업데이트

cd 코어코드/unity-mcp
git pull

Unity Package는 Package Manager에서 별도 업데이트 (버전 변경 시 Unity에서 수동 수행).

충돌·연동 실패 시 로그 확인

Claude Desktop 로그: %APPDATA%\Claude\logs\mcp-server-unityMCP.log
Unity Console: Window → General → Console
Unity MCP for Unity 창 하단 상태 표시

7. 관련 자산 (BT 조직 계승)

공유/조직공지/2026-04-22_Unity_MCP_연동_표준_워크플로우_v2.md — 조직공지 승격본 (본 가이드 요지)
공유/조직자산/시행착오_아카이브/개발_MCP연동_v1.md — BT3 도입 시행착오 타임라인·교훈
memory/org/feedback_mcp_setup_pitfalls.md — MCP 셋업 재발 방지 패턴 5종
공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md — 이전 프로젝트 Unity MCP v1 경험
공유/개발팀_자산/claude_desktop_config.example.json — Claude Desktop 설정 예시 (stdio 기본)
paths.local.json.template — PC별 경로 템플릿
setup/setup_windows.ps1 / setup_macos.sh — 자동 셋업 스크립트 (§3.7 unity-mcp clone)

9.2 KiB Raw Blame History