Quick Reference

MCP for Unity는 AI assistant가 Unity Editor API를 MCP tool로 호출하도록 연결하는 CoplayDev의 오픈소스 bridge입니다. Unity Technologies 공식 패키지가 아닙니다.

연결: MCP client -> Python MCP server -> WebSocket -> Unity Editor C# package
작업: scene·GameObject / asset·prefab·material / C# script / test·build
선택: Codex, Claude 같은 MCP client에서 Unity Editor를 직접 조회·수정할 때
요구 환경: 현재 문서 기준 Unity 2021.3~6.x, Python 3.10+, uv

stdio는 한 client와 로컬에서 시작하기 단순하고, HTTP transport는 여러 agent나 원격·공유 구성이 필요할 때 사용합니다. 지원 버전과 client 목록은 바뀔 수 있으므로 설치 전 최신 공식 문서를 다시 확인합니다.

설치와 연결

Unity Package Manager의 Add package from git URL에서 다음 package를 추가합니다. 재현 가능한 프로젝트가 필요하면 저장소가 안내하는 안정 tag를 URL fragment로 고정합니다.

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

설치 뒤 Window > MCP for Unity를 열고 Configure All Detected Clients를 실행하면 발견된 MCP client 설정을 준비합니다. 연결이 끝나면 큰 변경부터 시키지 말고 현재 scene이나 Console을 읽는 요청으로 대상 Unity instance와 tool 노출 상태를 먼저 확인합니다.

여러 Editor를 동시에 열었다면 active instance와 client session이 어느 프로젝트를 가리키는지 확인합니다. 연결은 됐는데 tool 호출이 다른 프로젝트로 향하는 문제는 package 재설치보다 instance routing을 먼저 점검합니다.

권한과 실패 경계

MCP for Unity는 scene, prefab, asset과 script를 실제로 수정하고 test와 build를 실행할 수 있습니다. client의 승인 설정만 믿지 말고 Git 작업 상태와 Unity Console을 함께 확인하며 작은 단위로 변경합니다.

• 읽기 요청으로 현재 project와 scene을 식별한 뒤 쓰기 tool을 사용합니다.
• script 변경 뒤에는 Unity compilation과 Console error가 끝났는지 확인합니다.
• asset 삭제, scene 저장과 build처럼 영향이 큰 작업은 대상 경로와 결과를 다시 승인합니다.
• 원격 HTTP server를 열 때는 공식 remote auth 안내와 방화벽을 적용하고 공개 network에 무인증으로 노출하지 않습니다.
• custom tool은 입력 검증과 수정 범위를 코드에서 제한합니다.

셸 명령 중심의 좁은 Unity 자동화가 목적이면 unity-cli가 더 단순할 수 있습니다. MCP, Skill과 Plugin의 역할 차이는 MCP, Skills, Plugins 구분에서 이어집니다.