유니티 MCP ✨

모델 컨텍스트 프로토콜을 사용하여 Unity Editor를 LLM에 연결합니다.

Unity MCP는 연결 역할을 하여 클로드(Claude), 커서(Cursor)와 같은 AI 어시스턴트가 로컬 MCP(Model Context Protocol) 클라이언트를 통해 Unity 에디터와 직접 상호 작용할 수 있도록 합니다. LLM 도구를 활용하여 Unity 내에서 에셋 관리, 씬 제어, 스크립트 편집, 작업 자동화를 수행할 수 있습니다.

주요 특징 🚀

🗣️ 자연어 제어: LLM에 Unity 작업을 수행하도록 지시합니다.
🛠️ 강력한 도구: 자산, 장면, 자료, 스크립트 및 편집 기능을 관리합니다.
🤖 자동화: 반복적인 Unity 워크플로를 자동화합니다.
🧩 확장 가능: 다양한 MCP 클라이언트와 함께 작동하도록 설계되었습니다.

LLM에서는 다음과 같은 기능을 사용할 수 있습니다.

read_console : 콘솔에서 메시지를 가져오거나 콘솔을 지웁니다.
manage_script : C# 스크립트(생성, 읽기, 업데이트, 삭제)를 관리합니다.
manage_editor : 편집기의 상태와 설정을 제어하고 쿼리합니다.
manage_scene : 장면을 관리합니다(로드, 저장, 생성, 계층 구조 가져오기 등).
manage_asset : 자산 작업(가져오기, 생성, 수정, 삭제 등)을 수행합니다.
manage_gameobject : 게임 객체를 관리합니다: 생성, 수정, 삭제, 찾기, 구성 작업.
execute_menu_item : 경로(예: "파일/프로젝트 저장")를 통해 메뉴 항목을 실행합니다.

Related MCP server: Unity MCP Server

작동 원리 🤔

Unity MCP는 두 가지 구성 요소를 사용하여 도구를 연결합니다.

Unity MCP Bridge: 에디터 내부에서 실행되는 Unity 패키지입니다. (패키지 관리자를 통해 설치됨)
Unity MCP 서버: 로컬에서 실행되어 Unity Bridge와 MCP 클라이언트 간 통신을 담당하는 Python 서버입니다. (수동으로 설치)

흐름: [Your LLM via MCP Client] <-> [Unity MCP Server (Python)] <-> [Unity MCP Bridge (Unity Editor)]

설치 ⚙️

참고: 패키지가 업데이트됨에 따라 설정은 지속적으로 개선되고 있습니다. 문제가 발생하면 다시 확인해 주세요.

필수 조건

Git CLI: 서버 코드를 복제합니다. Git 다운로드
Python: 버전 3.12 이상. Python 다운로드
Unity 허브 및 에디터: 버전 2020.3 LTS 이상. Unity 다운로드
uv(Python 패키지 관리자):
지엑스피1
MCP 클라이언트:
- 클로드 데스크탑
- 커서
- (다른 사람들은 수동 구성으로 작업할 수 있음)

1단계: Unity 패키지(Bridge) 설치

Unity 프로젝트를 엽니다.
Window > Package Manager 로 이동합니다.
+ -> Add package from git URL... 클릭합니다.
입력하다:
https://github.com/justinpbarnett/unity-mcp.git?path=/UnityMcpBridge
Add 클릭합니다.
이 프로세스의 결과로 MCP 서버가 자동으로 귀하의 컴퓨터에 설치됩니다.

2단계: MCP 클라이언트 구성

1단계에서 설치한 Python 서버에 MCP 클라이언트(Claude, Cursor 등)를 연결합니다.

옵션 A: 자동 구성(Claude/Cursor에 권장)

Unity에서 Window > Unity MCP 로 이동합니다.
Auto Configure Claude 또는 Auto Configure Cursor 클릭합니다.
녹색 상태 표시기 🟢와 "연결됨"을 확인하세요. (이 표시는 MCP 클라이언트의 구성 파일을 자동으로 수정합니다.)

옵션 B: 수동 구성

자동 구성이 실패하거나 다른 클라이언트를 사용하는 경우:

MCP 클라이언트의 구성 파일을 찾으세요. (클라이언트 설명서를 확인하세요.)
- Claude 예제(macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
- Claude 예제(Windows): %APPDATA%\Claude\claude_desktop_config.json
1단계의 정확한 경로를 사용하여 mcpServers 섹션을 추가/업데이트하도록 파일을 편집합니다 .

윈도우:

{ "mcpServers": { "UnityMCP": { "command": "uv", "args": [ "run", "--directory", "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\UnityMCP\\UnityMcpServer\\src", "server.py" ] } // ... other servers might be here ... } }

(YOUR_USERNAME을 바꾸고 이중 백슬래시(\)를 사용하는 것을 잊지 마세요)

맥OS:

{ "mcpServers": { "UnityMCP": { "command": "uv", "args": [ "run", "--directory", "/usr/local/bin/UnityMCP/UnityMcpServer/src", "server.py" ] } // ... other servers might be here ... } }

(~/bin을 사용하는 경우 YOUR_USERNAME을 바꾸세요)

리눅스:

{ "mcpServers": { "UnityMCP": { "command": "uv", "args": [ "run", "--directory", "/home/YOUR_USERNAME/bin/UnityMCP/UnityMcpServer/src", "server.py" ] } // ... other servers might be here ... } }

(YOUR_USERNAME을 바꾸세요)

사용법 ▶️

Unity 프로젝트를 엽니다. Unity MCP Bridge(패키지)가 자동으로 연결됩니다. Window > Unity MCP에서 상태를 확인하세요.
MCP 클라이언트(Claude, Cursor 등)를 시작하세요 . 설치 3단계의 구성을 사용하여 Unity MCP 서버(Python)가 자동으로 실행됩니다.
상호작용! 이제 MCP 클라이언트에서 Unity 도구를 사용할 수 있습니다.
예제 프롬프트: Create a 3D player controller.

기여하기 🤝

Unity MCP를 더욱 개선하는 데 도움을 주세요!

메인 저장소를 포크합니다 .
브랜치를 만듭니다 ( feature/your-idea 또는 bugfix/your-fix ).
변경 사항을 만듭니다.
커밋 (특징: 멋진 새로운 기능 추가).
지점을 밀어주세요 .
마스터 브랜치에 대한 풀 리퀘스트를 엽니다 .

문제 해결 ❓

Unity Bridge가 실행되지 않거나 연결되지 않음:
- Unity Editor가 열려 있는지 확인하세요.
- 상태 창을 확인하세요: 창 > Unity MCP.
- 유니티를 다시 시작합니다.
MCP 클라이언트가 연결되지 않음/서버가 시작되지 않음:
- 서버 경로 확인: MCP 클라이언트 JSON 설정에서 --directory 경로를 다시 확인하세요. 설치 1단계에서 UnityMCP 저장소를 복제한 위치와 정확히 일치해야 합니다(예: .../Programs/UnityMCP/UnityMcpServer/src).
- uv 확인: uv가 설치되어 작동하는지 확인하세요(pip show uv).
- 수동 실행: 터미널에서 서버를 직접 실행하여 오류를 확인해 보세요. # Navigate to the src directory first! cd /path/to/your/UnityMCP/UnityMcpServer/src uv run server.py
- 권한(macOS/Linux): 서버를 /usr/local/bin과 같은 시스템 위치에 설치한 경우, MCP 클라이언트를 실행하는 사용자에게 uv를 실행하고 해당 파일에 접근할 수 있는 권한이 있는지 확인하세요. ~/bin에 설치하는 것이 더 쉬울 수 있습니다.
자동 구성 실패:
- 수동 구성 단계를 사용하세요. 자동 구성에는 MCP 클라이언트 구성 파일에 쓸 수 있는 권한이 없을 수 있습니다.