MCP Unity Editor(게임 엔진)

지엑스피1

MCP Unity는 Unity Editor용 모델 컨텍스트 프로토콜(Model Context Protocol)을 구현하여 AI 어시스턴트가 Unity 프로젝트와 상호 작용할 수 있도록 지원합니다. 이 패키지는 Unity와 MCP 프로토콜을 구현하는 Node.js 서버를 연결하는 브리지 역할을 하며, Claude, Windsurf, Cursor와 같은 AI 에이전트가 Unity Editor 내에서 작업을 실행할 수 있도록 지원합니다.

특징

IDE 통합 - 패키지 캐시 액세스

MCP Unity는 Unity Library/PackedCache 폴더를 작업 공간에 추가하여 VSCode와 유사한 IDE(Visual Studio Code, Cursor, Windsurf)와의 자동 통합을 제공합니다. 이 기능은 다음과 같습니다.

• Unity 패키지의 코드 인텔리전스를 개선합니다.
• Unity 패키지에 대한 더 나은 자동 완성 및 유형 정보를 제공합니다.
• AI 코딩 어시스턴트가 프로젝트의 종속성을 이해하도록 돕습니다.

MCP 서버 도구

• execute_menu_item : Unity 메뉴 항목(MenuItem 속성으로 태그가 지정된 함수)을 실행합니다.

  예시 프롬프트: "새로운 빈 GameObject를 생성하려면 'GameObject/Create Empty' 메뉴 항목을 실행하세요."

• select_gameobject : 경로 또는 인스턴스 ID를 기준으로 Unity 계층 구조에서 게임 객체를 선택합니다.

  예시 프롬프트: "내 장면에서 메인 카메라 객체를 선택하세요"

• update_component : GameObject의 구성 요소 필드를 업데이트하거나 해당 구성 요소가 포함되어 있지 않으면 GameObject에 추가합니다.

  예시 프롬프트: "Player 객체에 Rigidbody 구성 요소를 추가하고 질량을 5로 설정하세요"

• add_package : Unity 패키지 관리자에 새 패키지를 설치합니다.

  예시 프롬프트: "내 프로젝트에 TextMeshPro 패키지를 추가하세요"

• run_tests : Unity Test Runner를 사용하여 테스트를 실행합니다.

  예시 프롬프트: "내 프로젝트에서 모든 EditMode 테스트를 실행하세요"

• notify_message : Unity Editor에 메시지를 표시합니다.

  예시 프롬프트: "작업이 완료되었음을 Unity에 알림으로 보냅니다."

• add_asset_to_scene : AssetDatabase에서 Unity 장면에 자산을 추가합니다.

  예시 프롬프트: "내 프로젝트의 Player 프리팹을 현재 장면에 추가하세요"

MCP 서버 리소스

• unity://menu-items : Unity Editor에서 사용 가능한 모든 메뉴 항목 목록을 검색하여 execute_menu_item 도구를 용이하게 합니다.

  예시 프롬프트: "GameObject 생성과 관련된 사용 가능한 모든 메뉴 항목을 보여주세요"

• unity://hierarchy : Unity 계층 구조의 모든 게임 객체 목록을 검색합니다.

  예시 프롬프트: "현재 장면 계층 구조를 보여주세요"

• unity://gameobject/{id} : 직렬화된 속성 및 필드가 있는 모든 GameObject 구성 요소를 포함하여 씬 계층 구조의 인스턴스 ID 또는 개체 경로를 통해 특정 GameObject에 대한 자세한 정보를 검색합니다.

  예시 프롬프트: "플레이어 게임 객체에 대한 자세한 정보를 알려주세요"

• unity://logs : Unity 콘솔에서 모든 로그 목록을 검색합니다.

  예시 프롬프트: "Unity 콘솔의 최근 오류 메시지를 보여주세요"

• unity://packages : Unity 패키지 관리자에서 설치된 패키지와 사용 가능한 패키지에 대한 정보를 검색합니다.

  예시 프롬프트: "현재 내 Unity 프로젝트에 설치된 모든 패키지를 나열하세요"

• unity://assets : Unity Asset Database에 있는 자산에 대한 정보를 검색합니다.

  예시 프롬프트: "내 프로젝트의 모든 텍스처 자산을 찾으세요"

• unity://tests/{testMode} : Unity Test Runner에서 테스트에 대한 정보를 검색합니다.

  예시 프롬프트: "Unity 프로젝트에서 사용 가능한 모든 테스트를 나열하세요"

요구 사항

• Unity 2022.3 이상 - 서버 설치
• Node.js 18 이상 - 서버를 시작 하려면
• npm 9 이상 - 서버 디버깅을 위해

설치

이 MCP Unity 서버를 설치하는 과정은 여러 단계로 구성됩니다.

1단계: Unity 패키지 관리자를 통해 Unity MCP 서버 패키지 설치

1. Unity 패키지 관리자를 엽니다(창 > 패키지 관리자)
2. 왼쪽 상단 모서리에 있는 "+" 버튼을 클릭하세요
3. "git URL에서 패키지 추가..."를 선택하세요.
4. 입력: https://github.com/CoderGamester/mcp-unity.git
5. "추가"를 클릭하세요

2단계: Node.js 설치

MCP Unity 서버를 실행하려면 컴퓨터에 Node.js 18 이상이 설치되어 있어야 합니다.

1. Node.js 다운로드 페이지를 방문하세요
2. LTS 버전용 Windows Installer(.msi)를 다운로드하세요(권장)
3. 설치 프로그램을 실행하고 설치 마법사를 따르세요
4. PowerShell을 열고 다음을 실행하여 설치를 확인하세요.
   node --version
5. Node.js 다운로드 페이지를 방문하세요
6. LTS 버전용 macOS 설치 프로그램(.pkg)을 다운로드하세요(권장)
7. 설치 프로그램을 실행하고 설치 마법사를 따르세요
8. 또는 Homebrew가 설치되어 있다면 다음을 실행할 수 있습니다.
   brew install node@18
9. 터미널을 열고 다음을 실행하여 설치를 확인하세요.
   node --version

3단계: AI LLM 클라이언트 구성

1. Unity Editor를 엽니다
2. 도구 > MCP Unity > 서버 창으로 이동합니다.
3. 아래 이미지에 표시된 대로 AI LLM 클라이언트의 "구성" 버튼을 클릭하세요.

4. 주어진 팝업으로 구성 설치를 확인하세요

Smithery를 통해 MCP Unity를 설치하려면:

AI 클라이언트의 MCP 구성 파일(예: Claude Desktop의 claude_desktop_config.json)을 열고 다음 텍스트를 복사합니다.

ABSOLUTE/PATH/TO MCP Unity 설치 경로로 바꾸거나 Unity Editor MCP 서버 창(도구 > MCP Unity > 서버 창)에서 텍스트를 복사하세요.

Unity Editor MCP 서버 시작

1. Unity Editor를 엽니다
2. 도구 > MCP Unity > 서버 창으로 이동합니다.
3. WebSocket 서버를 시작하려면 "서버 시작"을 클릭하세요.
4. Claude Desktop 또는 AI 코딩 IDE(예: Cursor IDE, Windsurf IDE 등)를 열고 Unity 도구 실행을 시작하세요.

AI 클라이언트가 WebSocket 서버에 연결되면 창의 녹색 상자에 자동으로 표시됩니다.

선택 사항: WebSocket 포트 설정

기본적으로 WebSocket 서버는 포트 8090에서 실행됩니다. 이 포트는 두 가지 방법으로 변경할 수 있습니다.

1. Unity Editor를 엽니다
2. 도구 > MCP Unity > 서버 창으로 이동합니다.
3. "WebSocket Port" 값을 원하는 포트 번호로 변경하세요.
4. Unity는 시스템 환경 변수 UNITY_PORT를 새 포트 번호로 설정합니다.
5. Node.js 서버를 다시 시작하세요
6. "서버 시작"을 다시 클릭하여 Unity Editor 웹 소켓을 Node.js MCP 서버에 다시 연결합니다.
7. 터미널에서 UNITY_PORT 환경 변수를 설정하세요
   • 파워쉘 GXP7
   • 명령 프롬프트/터미널 GXP8
8. Node.js 서버를 다시 시작하세요
9. "서버 시작"을 다시 클릭하여 Unity Editor 웹 소켓을 Node.js MCP 서버에 다시 연결합니다.

서버 디버깅

MCP Unity 서버는 Node.js를 사용하여 빌드됩니다. build 디렉터리에서 TypeScript 코드를 JavaScript로 컴파일해야 합니다. 서버를 빌드하려면 터미널을 열고 다음을 실행합니다.

1. 서버 디렉토리로 이동합니다.
   cd ABSOLUTE/PATH/TO/mcp-unity/Server
2. 종속성 설치:
   npm install
3. 서버를 빌드하세요:
   npm run build
4. 서버를 실행합니다:
   node build/index.js

@modelcontextprotocol/inspector를 사용하여 서버를 디버깅합니다.

• 파워셸

• 명령 프롬프트/터미널

터미널을 닫거나 MCP Inspector 로 디버깅하기 전에 Ctrl + C 로 서버를 종료하는 것을 잊지 마세요.

1. 터미널이나 log.txt 파일에 로깅을 활성화하세요.
   • 파워쉘 GXP15
   • 명령 프롬프트/터미널 GXP16

문제 해결

• WebSocket 서버가 실행 중인지 확인하세요(Unity의 서버 창 확인)
• 연결을 차단하는 방화벽 제한이 있는지 확인하세요.
• 포트 번호가 올바른지 확인하세요(기본값은 8080)
• Unity Editor MCP 서버 창에서 포트 번호를 변경하세요. (도구 > MCP Unity > 서버 창)
• Unity 콘솔에서 오류 메시지를 확인하세요.
• Node.js가 PATH에 제대로 설치되어 접근 가능한지 확인하세요.
• 모든 종속성이 서버 디렉토리에 설치되었는지 확인하세요.
• 메뉴 항목 경로가 올바른지 확인하세요(대소문자 구분).
• 메뉴 항목에 확인이 필요한지 확인하세요
• 메뉴 항목이 현재 컨텍스트에서 사용 가능한지 확인하세요.

지원 및 피드백

질문이 있거나 지원이 필요하면 이 저장소에서 이슈를 열어주세요.

또는 다음 연락처로 문의하실 수 있습니다.

• 링크드인:
• 디스코드: gamester7178
• 이메일: game.gamester@gmail.com

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출하거나 이슈를 개설하여 요청해 주세요.

기존 커밋 형식에 따라 변경 사항을 커밋합니다 .

특허

이 프로젝트는 MIT 라이선스 에 따라 진행됩니다.

감사의 말

• 모델 컨텍스트 프로토콜
• 유니티 테크놀로지스
• 노드.js
• 웹소켓-샤프