Unity Code MCP는 AI 에이전트가 Unity 코드를 자율적으로 작성할 수 있도록 지원하는 코딩 중심의 Model Context Protocol (MCP) 서버입니다.

Unity Code MCP는 Rust로 구축된 고성능 코딩 중심 MCP 서버입니다. 이 서버는 컴파일 피드백(Compilation feedback)과 테스트 실행(Test execution)이라는 자율적 코드 개발에 필요한 필수 도구만을 제공하면서, Unity의 컴파일 사이클을 유연하게 처리합니다.

이 MCP 서버를 통해 AI 에이전트는 마치 사람이 하는 것처럼 코드를 작성하고, 컴파일하고, 컴파일 에러를 수정하고, 테스트하고, 버그를 잡는 과정을 반복하며 탁월한 속도와 신뢰성으로 Unity 코드를 자율적으로 개발할 수 있습니다.

🤖 코딩 최적화 (Coding-Optimized): 효율적인 AI 에이전트 코딩 워크플로우를 위해 설계된 간소화된 도구
⚡ 경량 및 고성능 (Lightweight and High Performance): 탁월한 속도, 최소한의 메모리 사용량, 번개처럼 빠른 응답 시간을 위해 Rust로 구축되었습니다. 워크스페이스가 Unity 프로젝트가 아닐 때는 1MB의 메모리만 사용하며, Unity 프로젝트이고 Unity Editor가 열려 있는 경우에도 10MB만 사용합니다. 또한, Unity Editor와의 통신은 UDP를 기반으로 하므로 시스템 부하가 최소화됩니다.
🎯 효율적인 통신 (Efficient Communication): 필수 작업만 수행하여 토큰 사용량을 최소화하고 관련 정보만 반환
🧪 테스트 주도 (Test-Driven): 포괄적인 테스트 실행 및 보고 기능
📦 독립형 (Self-Contained): 런타임 의존성이 없는 단일 바이너리 (Node.js, Python 또는 .NET 불필요)

Unity Code MCP는 자율적인 코드 개발을 위해 2가지 도구를 제공합니다:

• Unity 컴파일 및 에셋 프로세싱(Asset processing) 트리거
• 컴파일 에러 및 기타 컴파일 경고와 에러 반환 (새로고침 중에는 로그만 포함) - 도메인 리로드(Domain reload)를 유연하게 처리

에셋 데이터베이스 새로고침(Asset database refresh) 도구 작동 방식:

• 포괄적인 보고 기능과 함께 Unity 테스트 실행
• 실패 시 상세한 스택 트레이스(Stack traces) 및 로그 제공
• EditMode 및 PlayMode 테스트 모두 지원

테스트 실행(Test execution) 도구 작동 방식:

설정이 완료되면, AI 에이전트는 Unity 코드를 완전히 자율적으로 개발할 수 있습니다.

사용자: "WASD 키로 이동하고 점프 기능이 있는 플레이어 컨트롤러를 생성해줘. 반드시 테스트를 완벽하게 수행해야 해."
AI: 이동과 점프 기능이 포함된 완전한 플레이어 컨트롤러를 생성한 후, 포괄적인 테스트를 작성하겠습니다.
1. [AI가 이동 로직이 포함된 PlayerController.cs를 작성함]
...

이는 사용자의 요청부터 인간의 개입 없이 완전히 테스트된 작동 가능한 Unity 코드에 이르기까지, 진정한 자율적 개발 (Autonomous development)을 보여줍니다.

작동 중인 AI 에이전트의 예시: 컨텍스트(Context) 없이 Kimi K2에게 Unity 프로젝트의 컴파일 에러를 수정하라고 명령할 때:

• Unity 6.0 이상
• Rust 툴체인 (Rust toolchain, 소스 빌드용)
• CMake 및 C 컴파일러 (의존성 빌드에 필요)

Unity 프로젝트에 Visual Studio Code Editor 패키지를 설치하십시오.

중요: unity_code_mcp가 작동하려면 Visual Studio Code Editor 패키지가 활성화(enabled)되어 있어야 합니다 (즉, Visual Studio Code Editor에서 제공하는 외부 스크립트 에디터를 외부 스크립트 에디터로 선택해야 활성화됩니다). Unity의 Preferences에서 이를 확인하십시오.

→ External Tools

→ External Script Editor

• "Visual Studio Code Editor v1.0.12 enabled"와 같은 메시지가 표시되어야 합니다.

옵션 A: 릴리스 다운로드 (Download Release) (권장) (Windows 전용)

• Releases 페이지에서 최신 바이너리(binary)를 다운로드하십시오.

옵션 B: 소스에서 빌드 (Build from Source)

cargo build --release

AI 어시스턴트 설정에 MCP 서버를 추가하십시오:

Cursor/Trae의 경우:

{
"mcpServers": {
"unity-code": {
...

MCP 확장이 설치된 VS Code의 경우:

{
"mcp.servers": {
"unity-code": {
...

Claude Desktop의 경우:

{
"mcpServers": {
"unity-code": {
...

참고: UNITY_PROJECT_PATH 환경 변수 (environment variable)는 대체 옵션(fallback option)입니다. 만약 사용 중인 IDE가 MCP의 roots 기능을 지원한다면, 서버는 제공된 워크스페이스 루트(workspace roots)로부터 Unity 프로젝트를 자동으로 감지하며, 환경 변수보다 이를 우선시합니다.

문제 해결 (Troubleshooting): IDE에서 ${workspaceFolder}가 작동하지 않는 경우, 대신 절대 경로를 사용해 보십시오. 예: "UNITY_PROJECT_PATH": "/absolute/path/to/your/unity/project"

또는, IDE 개발자에게 MCP roots 기능 지원을 추가해 달라고 요청하십시오.

중요: 바이너리 명령에는 반드시 절대 경로를 사용하십시오.

이 코드는 크로스 플랫폼 (cross platform)을 지원하지만, 저는 Windows만 사용하기 때문에 다른 플랫폼을 위한 빌드나 테스트는 수행할 수 없습니다. 플랫폼 특유의 버그가 발생할 경우 직접 수정해야 합니다.

테스트 스위트 (test suite) 실행 방법:

• Unity Editor 시작: 내장된 테스트 프로젝트로 시작합니다.

  Unity Editor를 열고 다음 프로젝트를 로드합니다:

  ./UnityProject

• 테스트 실행 (Unity 충돌을 방지하기 위해 단일 스레드로 실행):
  cargo test -- --test-threads=1

참고: 테스트를 실행하려면 내장된 프로젝트가 로드된 Unity Editor 인스턴스가 실행 중이어야 합니다. Unity Editor와의 상호 작용으로 인해 테스트 완료까지 30~60초 정도 소요될 수 있습니다.

C 컴파일러 (C Compiler): aws-lc-rs 의존성을 빌드하는 데 필요합니다.

• Windows: MSVC (Visual Studio Build Tools)
• macOS: Xcode Command Line Tools (xcode-select --install)
• Linux: GCC (Ubuntu/Debian의 경우 sudo apt-get install build-essential)

CMake: aws-lc-rs 의존성을 빌드하는 데 필요합니다.

• Windows: 공식 가이드를 따르십시오.
• macOS: brew install cmake
• Linux: sudo apt-get install cmake (Ubuntu/Debian)

# 디버그 빌드 (Debug build)
cargo build
# 릴리스 빌드 (Release build, 프로덕션 권장)
...

기여(Contributions)를 환영합니다! 다음 절차를 따라주세요:

• 저장소(repository)를 포크(Fork)합니다.
• 기능 브랜치(feature branch)를 생성합니다.
• cargo test -- --test-threads=1 명령으로 테스트를 실행합니다.
• 풀 리퀘스트(pull request)를 제출합니다.

이 프로젝트는 MIT 라이선스(MIT License) 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하십시오.

• Visual Studio Code Editor for Unity - 필수 Unity 패키지
• Model Context Protocol - 프로토콜 명세(specification)
• Unity Code Pro VS Code Extension - 관련 VS Code 확장 프로그램