Claude Code를 Unity MCP에 연결하는 방법: 설치 및 구성

이 가이드에서 다루는 내용

다음 다섯 단계를 따라 Unity MCP를 로컬 Unity 프로젝트에 연결하면 Claude CLI가 디스크의 스크립트를 편집하는 것을 넘어 에디터를 조작하고, 미리 보고, 디버깅할 수 있습니다.

완료하면 다음을 할 수 있습니다:

• Package Manager의 Add package from disk로 Unity MCP 가져오기
• 플러그인 활성화 완료(계정 또는 활성화 코드—Mcp Panel 안내를 따르세요)
• 로컬 Unity MCP Server 시작(기본 포트 6589)
• Quick setup에서 CLI 명령 복사 후 Claude CLI에서 실행하고 MCP 연결 확인

다운로드 페이지: Unity MCP

이 가이드는 Claude CLI를 사용합니다. Gemini CLI의 경우 Quick setup에서 해당 클라이언트를 선택하고 같은 방식으로 CLI 명령을 복사하세요.

사전 요구 사항

항목	비고
Unity	2022.3+ / Unity 6 권장(사용 중인 빌드의 최신 지원 안내를 따르세요)
플러그인 패키지	다운로드하고 압축을 푼 Unity MCP 아카이브
활성화	플러그인 계정 + 비밀번호, 또는 이메일 + 활성화 코드(Mcp Panel 기준)
AI IDE	Claude CLI(Gemini CLI도 동일한 흐름)
로컬 네트워크	MCP 브리지는 보통 127.0.0.1에서 실행됩니다—포트를 공개적으로 노출하지 마세요

1단계: Unity MCP 다운로드

Unity MCP 공급업체 사이트 또는 릴리스 페이지에서 플러그인을 다운로드하세요:

예시 다운로드 페이지: https://www.vberai.com/game-engines/unity?ch=CQZLC2FG

권장 흐름:

1. 다운로드 페이지를 열고 Unity MCP 아카이브 받기
2. 로컬에 저장하고 고정된 폴더에 압축 해제(다음 단계에서 내부의 package.json 필요)
3. Unity를 열기 전에 압축을 푼 폴더에 package.json이 있는지 확인

라이선스 및 에디션 차이는 공급업체마다 다릅니다—공식 문서를 따르세요.

2단계: 패키지 가져오기

1. 대상 Unity 프로젝트 열기
2. 메뉴 Window → Package Manager
3. Package Manager 패널 왼쪽 상단의 + 클릭
4. Add package from disk 선택
5. 1단계에서 압축을 푼 폴더의 package.json 파일 선택

가져오기에 성공하면 Unity MCP 패키지가 Package Manager 목록에 나타납니다.

3단계: unity-mcp 활성화

1. 메뉴 Window → Unity MCP → Mcp Panel
2. 활성화 화면에서 다음 중 하나:
   • 계정 + 비밀번호로 로그인
   • 또는 이메일 + 활성화 코드 입력
3. 활성화가 성공하면 MCP Server 설정 페이지 열기(다음 단계)

활성화 없이는 일반적으로 서비스가 시작되지 않습니다. 계정 또는 코드가 설치한 플러그인 버전과 일치하는지 확인하세요.

4단계: unity-mcp-server 시작

1. 활성화 후 Unity MCP Server 설정 페이지 열기
2. 필요에 따라 조정:
   • Port: 기본 6589
   • Language: UI 환경 설정에 맞춤
   • Startup: 패널 옵션 따르기(예: 사용 가능한 경우 에디터와 함께 자동 시작)
3. Start service 클릭
4. 패널에 Running이 표시되면 Unity MCP Server가 실행 중입니다

이제 로컬 MCP 브리지가 준비되었습니다—다음으로 Claude CLI를 구성하세요.

5단계: Claude CLI 구성

1. Tool management 열기
   • Unity MCP Server가 노출하는 도구 검토
   • 모델이 사용하길 원하는 것만 활성화
2. Quick setup 열기
   • Claude CLI 선택(Gemini CLI도 동일—해당 클라이언트 선택)
   • Claude CLI / Gemini CLI는 Auto configure를 지원하지 않습니다—패널에 표시된 CLI 명령에서 Copy 클릭

3. 시스템 터미널을 열고 복사한 명령을 붙여넣고 실행(Claude CLI가 설치된 환경에서)
4. Claude CLI로 돌아가 MCP 목록에 unity-mcp(또는 등록된 동등한 이름)가 나타나는지 확인

연결 후 빠른 확인

Claude CLI에서 읽기 전용 확인부터 시작하세요. 예:

Unity에서 현재 열려 있는 씬의 Hierarchy 루트 오브젝트를 나열해 줘.

응답이 에디터와 일치하면 브리지가 정상입니다. 그런 다음 작은 쓰기(임시 빈 GameObject를 만들고 삭제)를 시도하여 권한과 도구 선택을 확인하세요.

FAQ

Add package from disk에서 package.json을 찾을 수 없나요?
1단계에서 아카이브를 완전히 압축 해제했는지, 그리고 중첩된 추출 폴더가 아닌 해당 폴더의 루트에 있는 package.json을 선택했는지 확인하세요.

활성화가 계속 실패하나요?
계정 또는 활성화 코드가 유효하고 만료되지 않았으며 올바른 이메일에 연결되어 있는지 확인한 후 Mcp Panel에서 다시 시도하세요.

서비스를 시작했는데 Running이 아니라고요?
포트 6589(또는 사용자 지정 포트)가 비어 있고 localhost가 차단되지 않았는지 확인하세요. 3단계 활성화가 성공했는지 확인하세요.

Claude CLI에 unity-mcp가 표시되지 않나요?
Unity가 여전히 Running을 표시하는지 확인하고, Quick setup으로 돌아가 CLI 명령을 다시 복사한 후 터미널에서 완전히 실행하세요. Cursor가 아닌 Claude CLI를 선택했는지 확인하세요. Gemini CLI의 경우 Gemini CLI를 선택하고 해당 클라이언트의 명령을 복사하세요.

다음 단계

• 자연어 씬 쿼리나 작은 편집을 시도하여 도구 경계를 익히세요
• 큰 변경 전에 커밋하고, 브리지는 localhost에만 유지하세요
• 연결 후 프롬프트 패턴: Unity MCP with Claude Code and Cursor