Unity로 게임을 만들고 싶지만, 평소 업무에서 Unity를 사용할 기회가 없어 에디터 조작(GameObject 배치, 컴포넌트(Component) 부착, 씬(Scene) 구축 등)이 좀처럼 익숙해지지 않는——그런 고민을 안고 있었습니다. 코드 자체는 쓸 수 있는데, 에디터 상에서의 「배치」 「조립」 부분에서 항상 손이 멈춰버린다는 분들은 적지 않을 것이라고 생각합니다.

그래서 찾아낸 것이 Unity-MCP입니다. Claude Code 등의 에이전트(Agent)로부터 자연어로 Unity 에디터를 직접 조작할 수 있는 OSS 툴로, 「씬에 정육면체를 하나 만들어줘」와 같은 지시만으로 실제로 Unity 상에 오브젝트가 생성됩니다.

본 기사에서는 이 Unity-MCP를 Claude Code와 연계하여 셋업하는 절차와, 실제로 마주한 트러블 및 그 해결 방법을 정리합니다. 순조롭게 진행하면 몇 분 정도의 작업이지만, 이번에는 접속 에러로 고생했기 때문에 그 트러블슈팅(Troubleshooting)을 포함하여 기록해 두겠습니다.

• 리포지토리(Repository): IvanMurzak/Unity-MCP
• 라이선스(License): Apache-2.0 (상업적 이용도 무료)
• 2026년 6월 시점에서 GitHub 스타 3,000개 초과
• 대응 Unity 버전:
  2022.3 이후 (LTS 버전이면 OK. 이번에는 2022.3.48f1에서 동작 확인)

Unity-MCP는 70개 이상의 MCP 툴을 표준 탑재하고 있으며, 다음과 같은 조작을 자연어로부터 실행할 수 있습니다.

• GameObject의 생성·복제·삭제·부모 자식 관계 설정
• 컴포넌트(Component)의 추가·편집
• 머티리얼(Material)·프리팹(Prefab)의 생성
• 씬(Scene)의 생성·저장·전환
• C# 스크립트의 읽기/쓰기·동적 실행 (Roslyn에 의한 컴파일)
• 콘솔 로그(Console Log) 취득
• 프로파일러(Profiler)를 통한 퍼포먼스(Performance) 측정

대응 에이전트(Agent)는 Claude Code, Claude Desktop, GitHub Copilot, Cursor, Gemini CLI 등 폭넓으며, 이번에는 Claude Code를 사용했습니다.

• Unity 2022.3 이후
• Node.js / npm이 설치되어 있을 것
• 프로젝트 경로에 공백을 포함하지 않을 것 (예: C:/MyProjects/MyProject는 OK, C:/My Projects/MyProject는 NG)

npm install -g unity-mcp-cli

대상 Unity 프로젝트 경로를 지정하여 실행합니다.

unity-mcp-cli install-plugin "C:\Users\xxxx\ProjectName"

√ Resolved plugin version: 0.83.1
✔ Updated C:\Users\xxxx\ProjectName\Packages\manifest.json
ℹ Installing Unity-MCP plugin v0.83.1 into: C:\Users\xxxx\ProjectName
...

Packages/manifest.json에 OpenUPM의 스코프(Scope) 지정 레지스트리(package.openupm.com)가 자동으로 추가됩니다.

unity-mcp-cli open "C:\Users\xxxx\ProjectName"

관리자 권한으로 연 터미널에서 unity-mcp-cli open을 실행하면, Unity 에디터도 관리자 권한을 승계해 버려 다음과 같은 경고가 표시되었습니다.

Unity is running with Administrator privileges, which is not supported...

대처법: 「Restart Unity as a standard user」를 선택하여 표준 사용자 권한으로 재시작합니다. 이후의 작업도 관리자 권한이 아닌 일반 터미널에서 진행합니다.

Unity 에디터를 열면, Package Manager 설정 화면에 Scoped Registry 추가 다이얼로그가 표시되었습니다.

이는 install-plugin이 Packages/manifest.json에 OpenUPM의 레지스트리(Scope: com.ivanmurzak)를 추가한 것을 Unity가 감지한 것입니다. 「Close」를 누른 후, Package Manager 화면의 「Apply」 버튼으로 설정을 확정합니다.

Apply가 비활성화(Grayed out)되어 있다면, 이미 설정이 반영되어 저장할 변경 사항이 없는 상태이므로 문제없습니다. 왼쪽 메뉴에 「AI Game Developer」 항목이 추가되어 있다면 플러그인 통합에 성공한 것입니다.

Window > AI Game Developer

를 열면 연결 설정 화면이 표시됩니다. 기본값은 「Cloud」 모드로 되어 있었습니다.

외부 서비스에 대한 의존이나 인증을 피하고 싶다면 「Custom」 탭으로 전환합니다. 인증(Authorize)이 필요하지 않게 되며, 로컬에서 완결되는 http://localhost:xxxxx를 경유하여 연결됩니다.

「AI agent」 섹션에서 Claude Code를 선택하면 「Setup Required」로서 두 가지 항목이 표시됩니다.

Skills(권장): 맨 위의 「Enable Skills」 버튼으로 활성화 -
MCP Configuration: 「Configure」 버튼으로 .mcp.json을 생성

이 부분이 이번에 막혔던 포인트였습니다. Skills의 「Auto-generate」에 체크하고 「Generate」 버튼을 눌러도, AI agent의 상태가 여전히 빨간색이었습니다.

원인은 Skills(사용법 설명)와 MCP Configuration(연결 설정 그 자체)은 별개이며, 두 가지 모두 설정해야 했기 때문입니다. 「Model Context Protocol (MCP)」 란의 「Configure」 버튼도 눌러서 .mcp.json을 생성함으로써 해결했습니다.

확장 기능(Extensions)으로 Animation, Tilemap, ProBuilder 등도 준비되어 있습니다. 2D 게임이라면 나중에 Tilemap 확장이 유용할 것 같습니다.

MCP Configuration을 설정한 후에도 Console에 대량의 경고가 계속해서 나타났습니다.

에러 로그를 확인하니 다음과 같은 것이 근본 원인이었습니다.

fail: [AI] McpManagerClientHub McpManagerClientHub Version handshake failed: No response from server.

Unity(클라이언트)가 MCP 서버에 접속하려고 했으나, 서버로부터 응답이 없는 상태입니다.

Windows Defender의 차단을 의심 → 보호 기록을 확인했으나, unity-mcp-server.exe 개별 차단 기록은 없음. 이번에는 무관했습니다. -
서버 프로세스 유무 확인 → 작업 관리자에서 unity-mcp-server.exe는 보이지 않지만, netstat -ano로 포트는 실제로 LISTENING 상태. 모순됨 = 무언가 이상하다는 징후. -
Unity.exe의 다중 실행을 의심 → 작업 관리자에서 검색하니, Unity.exe가 3개 동시에 실행 중이었습니다. 관리자 권한으로 재시작하거나 CLI로 여러 번 실행하면서 오래된 프로세스가 남아 있었던 것 같습니다.

모든 프로세스를 종료하고 재시작 → 태스크를 모두 종료하고 Unity 에디터를 하나만 깨끗하게 다시 실행했지만, 그래도 해결되지 않음. -
좀비 프로세스 발견 → netstat -ano에서 보였던 PID를 작업 관리자의 표시와 대조해 보니, Unity.exe를 전부 종료했음에도 불구하고 오래된 서버 프로세스의 PID만 포트를 점유한 채 남아 있었습니다.

netstat -ano | findstr 20357
TCP 0.0.0.0:20357 0.0.0.0:0 LISTENING 21028
TCP [::]:20357 [::]:0 LISTENING 21028

# PID를 직접 지정하여 강제 종료
taskkill /PID 21028 /F

# 포트가 해제되었는지 확인
netstat -ano | findstr 20357
# → 아무것도 표시되지 않으면 해제 성공

깨끗한 상태로 재시작 → 포트 해제 후 unity-mcp-cli open으로 다시 열었더니, 무사히 「Unity: Connected」와 「MCP server: Running」이 모두 초록색이 되었습니다.

교훈: Unity-MCP는 특정 포트(프로젝트 경로의 SHA256 해시로부터 결정되는 고정 포트)에서 서버를 대기합니다. Unity 에디터를 강제 종료하거나, 관리자 권한 ⇔ 표준 사용자 전환으로 재시작을 반복하면, 서버 프로세스만 좀비화(Zombie process)되어 포트를 점유한 채 남는 경우가 있는 것 같습니다. 연결 에러가 발생하면, 우선 netstat -ano | findstr <포트 번호>로 포트 상태를 확인하고, 해당 PID를 taskkill /PID <PID> /F로 강제 종료하는 것이 유효한 대처법이었습니다.

모든 연결이 초록색이 되면, 프로젝트 폴더에서 Claude Code를 열고 지시를 내립니다.

MCP 도구 실행 허가를 요청받으므로, 내용을 확인하고 허가합니다(반복해서 사용할 경우 「이 프로젝트에서는 향후 허가」를 선택하면 이후 과정이 원활합니다).

Game View를 확인하면, 실제로 정육면체(Cube)가 생성되어 있었습니다.

자연어 지시만으로 실제로 Unity 씬(Scene)에 오브젝트가 생성되는 일련의 동작을 확인할 수 있었습니다.

Unity-MCP를 사용함으로써, "코드는 작성할 수 있지만 에디터 조작에는 익숙하지 않은" 엔지니어도 자연어 지시만으로 씬 구축을 진행할 수 있게 됩니다. 특히, 아트 담당·디자인 담당과 프로그래머가 분업하고 있는 팀에서는, 프로그래머 측이 에셋(Asset)의 임시 배치까지 AI를 통해 빠르게 진행하고, 나중에 디자이너가 실제 에셋으로 교체하는 방식의 분담도 수월해질 것으로 보입니다.

셋업 자체는 본래 몇 분이면 끝나는 작업이지만, 이번처럼 관리자 권한 전환이나 여러 번의 재시작을 거치면 서버 프로세스가 좀비화되어 연결 에러로 이어질 수 있습니다. 유사한 에러를 겪으신 분은 우선 netstat으로 포트 상태를 확인해 보시는 것을 추천합니다.

앞으로 실제 게임 제작을 통해 사용성을 검증해 나갈 예정입니다.