local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

Provides comprehensive control over the Unity Editor, enabling programmatic manipulation of assets, scene management, material editing, script creation/editing, and automation of editor functions like undo, play, and build.

유니티 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 : 경로(예: "파일/프로젝트 저장")를 통해 메뉴 항목을 실행합니다.

작동 원리 🤔

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 클라이언트 구성 파일에 쓸 수 있는 권한이 없을 수 있습니다.

아직도 해결되지 않으셨나요? 문제를 공개하세요 .

라이센스 📜

MIT 라이선스. 라이선스 파일을 참조하세요.

연락처 👋

X/트위터: @justinpbarnett

감사의 말 🙏

기여자와 Unity 팀에 감사드립니다.

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

모델 컨텍스트 프로토콜을 통해 Unity와 대규모 언어 모델 간의 원활한 통신을 가능하게 하는 브리지로, 개발자는 워크플로를 자동화하고, 자산을 조작하고, Unity 에디터를 프로그래밍 방식으로 제어할 수 있습니다.

Related Resources

Reddit Discussion about this server