Unity MCP Server

Unity Editor용 MCP 서버입니다. Claude Code 같은 AI 에이전트가 프로젝트를 검사하고, 조작하고, 테스트하고, 스크린샷을 찍을 수 있게 해줍니다.

주요 기능

• 도구 73개: 씬, 게임 오브젝트, 컴포넌트, 프리팹, 트랜스폼, 테스트, 리플렉션 + 디컴파일, C# eval, UI 캡처

• 제로 구성 클라이언트: 머신당 한 번의 클릭(또는 한 줄의 명령)으로 모든 프로젝트와 에디터가 자동으로 연결됩니다. 포트, 토큰, 프로젝트별 구성이 필요 없습니다

• 멀티 에디터 안전: 열려 있는 각 프로젝트가 자체 서버를 실행하며, 세션은 자동으로 올바른 서버로 라우팅됩니다

• MCP 리소스: 콘솔 로그, 씬 계층 구조, 테스트 결과, 프로젝트 파일

• Unity 2022.3+(Unity 6 권장), Node.js 18+

Related MCP server: Unity MCP Server

설치

Package Manager > + > Add package from git URL:

https://github.com/Singtaa/UnityMCP.git

또는 Packages/com.singtaa.unity-mcp에 클론/서브모듈로 추가합니다.

설정 (머신당 한 번)

1. Unity에서 프로젝트를 엽니다. 서버가 자동으로 시작되고, 런처가 ~/.unity-mcp/stdio.js로 배포됩니다.

2. Window > Unity MCP Server > Set up Claude Code

완료. 터미널에서도 동일합니다:

# macOS / Linux
claude mcp add --scope user --transport stdio unity -- node ~/.unity-mcp/stdio.js

# Windows
claude mcp add --scope user --transport stdio unity -- node "%USERPROFILE%\.unity-mcp\stdio.js"

이제 모든 Unity 프로젝트 안의 모든 Claude Code 세션은 해당 프로젝트의 에디터에 도달합니다. 여러 에디터를 나란히 실행해도 각 세션은 자신의 에디터를 찾습니다. 에디터가 닫혀 있거나 리로드 중이면 도구는 명확한 오류를 반환하고 스스로 복구됩니다. 세션 도중 에디터를 열어도 작동합니다: 에디터가 닫힌 상태에서 시작된 세션은 도구 목록을 즉시 등록하고(프로젝트별 캐시에서 제공), 에디터가 올라오는 순간 라이브로 다시 동기화되므로 클라이언트 재시작이 필요 없습니다.

내부 동작: 에디터는 세션별 비콘(Temp/UnityMcp_Endpoint.json, 종료 시 제거되어 오래된 상태로 남지 않음)을 작성합니다. 런처는 세션의 프로젝트(CLAUDE_PROJECT_DIR, 없으면 cwd에서 상위로 올라가며 탐색, UNITY_MCP_PROJECT가 둘 다 덮어씀)를 확인하고, MCP를 해당 프로젝트의 라이브 엔드포인트로 프록시하며 매 요청마다 비콘을 다시 읽습니다. tools.listChanged를 선언하고 비콘을 감시합니다: 에디터가 나타나면(또는 다른 에디터가 프로젝트를 인계하면) list_changed 알림을 내보내 클라이언트가 세션 중에 도구 및 리소스 목록을 다시 가져옵니다. ~/.unity-mcp/stdio.js로의 런처 배포는 LAUNCHER_VERSION이 올라갈 때만 업그레이드되므로, 서로 다른 패키지 버전의 에디터가 이 파일을 두고 충돌하지 않습니다.

다른 MCP 클라이언트: 동일한 런처를 사용하거나 일반 HTTP를 사용합니다(엔드포인트 + 토큰이 창에 표시됨).

도구

주목할 만한 도구:

• unity_eval: 에디터에서 C# 스니펫을 컴파일 + 실행하며 도메인 리로드가 없습니다. 표현식 형태는 값을 반환하고, 문(statement) 형태는 return을 사용합니다. 일반적인 using이 임포트되고, 앞부분의 using 줄은 끌어올려집니다. 번들된 Roslyn이 사용됩니다(C# 9 상한). 첫 호출은 몇 초간 워밍업한 후 컴파일당 수십 밀리초가 걸립니다

• unity_capture_panel: UI Toolkit PanelSettings를 오프스크린으로 PNG에 렌더링하며, 씬 크롬 없이 에디트 모드와 플레이 모드에서 작동합니다. 활성 UIDocument를 자동 감지합니다

• unity_assets_find: Project 창 쿼리 구문(t:Material, t:Prefab ui, l:MyLabel), 선택적 폴더 범위 지정, 총 개수와 함께 결과 상한

• unity_reflection_decompile: 로드된 모든 타입 또는 메서드의 전체 C# 소스

• 특이사항: 도메인 리로드 후 테스트 도구를 사용하기 전에 ~1s 기다리세요. unity_capture_game_view는 Unity 6.3+에서 플레이 모드 전용입니다

리소스

unity://console/logs · unity://hierarchy · unity://hierarchy/{scene} · unity://tests/results · unity://project/files

구성

ProjectSettings/McpSettings.json(커밋 대상): HTTP 포트 5173, IPC 포트 52100, 자동 시작, 인증 토큰.

포트가 다른 프로젝트의 서버에 의해 사용 중인가요? 사용 가능한 포트 쌍이 자동 할당되어 머신별로 UserSettings/McpPortOverride.json(gitignore됨)에 저장되므로, 포트 변동이 팀에 전파되지 않습니다. 프로젝트 ID는 모든 브리지 연결에서 검증됩니다: 포트가 잘못 구성되어 있어도 에디터는 다른 프로젝트의 서버를 절대 채택할 수 없습니다.

수동 서버 시작: MCP_PROJECT_ROOT를 프로젝트 경로로 설정한 상태에서 node src/server.js를 실행합니다.

Unity CLI와 함께 사용

경쟁이 아니라 보완 관계입니다:

• Unity CLI가 에디터 수명 주기를 담당합니다: 설치, unity open, 빌드, CI

• UnityMCP가 라이브 에디터 세션을 담당합니다: UI 캡처, 디컴파일, eval, 테스트 루프, 제로 구성 라우팅

• 일반적인 에이전트 루프: CLI로 unity open <project> 실행 → 에디터 부팅 → 서버 + 비콘 시작 → 런처 연결. 어느 쪽도 구성이 필요 없습니다

• CLI로 시작된 에디터는 포커스 없이 / 백그라운드에서 실행됩니다. UnityMCP는 정확히 그런 상황에 맞게 빌드되고 테스트되었습니다(백그라운드 안전 시작, 도메인 리로드 시 재시도)

• 포트나 도구 이름 충돌이 없습니다. 둘 다 등록하세요

아키텍처

┌─────────────────────────────────────────────────────────────┐
│                      AI Assistant                           │
├──────────────────────────────┬──────────────────────────────┤
│  stdio launcher              │  (or direct HTTP clients)    │
│  ~/.unity-mcp/stdio.js       │                              │
│  resolves the session's      │                              │
│  project, reads its beacon   │                              │
│  Temp/UnityMcp_Endpoint.json │                              │
├──────────────────────────────┴──────────────────────────────┤
│           HTTP JSON-RPC (Port 5173, per project)            │
├─────────────────────────────────────────────────────────────┤
│              Node.js MCP Server (Server~/)                  │
├─────────────────────────────────────────────────────────────┤
│                TCP NDJSON (Port 52100)                      │
├─────────────────────────────────────────────────────────────┤
│                Unity Editor C# Bridge                       │
│  (McpBridge → ToolRegistry → MainThreadDispatcher)          │
├─────────────────────────────────────────────────────────────┤
│                     Unity APIs                              │
└─────────────────────────────────────────────────────────────┘

열려 있는 각 프로젝트는 자체 Node 서버를 실행합니다. 런처는 모든 세션을 올바른 서버로 라우팅하는 공용 프런트 도어입니다.

개발

• Unity 테스트: Window > General > Test Runner (EditMode + PlayMode)

• 런처 테스트: Server~/에서 npm test

• 변경 로그: CHANGELOG.md

라이선스

MIT. LICENSE를 참조하세요.