Ollama 통합을 통한 Unity MCP

Ollama를 통해 Unity와 로컬 대용량 언어 모델(LLM) 간의 원활한 통신을 지원하는 Unity MCP(Model Context Protocol) 패키지입니다. 이 패키지는 justinpbarnett/unity-mcp를 확장하여 로컬 LLM과 연동되므로 개발자는 클라우드 기반 LLM에 의존하지 않고도 워크플로를 자동화하고, 애셋을 조작하고, Unity 에디터를 프로그래밍 방식으로 제어할 수 있습니다.

개요

Ollama 통합을 통한 Unity MCP는 다음 간의 양방향 통신 채널을 제공합니다.

1. Unity(C#를 통해)
2. Python MCP 서버
3. Ollama를 통해 운영되는 지역 LLM

이를 통해 다음이 가능합니다.

• 자산 관리 : Unity 자산을 프로그래밍 방식으로 생성, 가져오기 및 조작
• 장면 제어 : 장면, 객체 및 해당 속성 관리
• 재료 편집 : 재료 및 해당 속성 수정
• 스크립트 통합 : Unity 스크립트 보기, 생성 및 업데이트
• 편집기 자동화 : 실행 취소, 다시 실행, 재생 및 빌드와 같은 Unity 편집기 기능을 제어합니다.

인터넷 연결이나 API 키가 필요 없이, 자체 로컬 LLM을 통해 모두 구동됩니다.

지원 모델

이 구현은 다음 Ollama 모델에서 작동하도록 특별히 구성되었습니다.

• deepseek-r1:14b - 강력한 추론 기능을 갖춘 140억 개의 매개변수 모델
• gemma3:12b - 우수한 일반 기능을 갖춘 Google의 120억 매개변수 모델

Unity MCP 창에서 이러한 모델 간에 쉽게 전환할 수 있습니다.

설치(자산 방식)

Unity 패키지 관리자 호환성 문제로 인해 Asset Method를 사용하여 설치하는 것이 좋습니다.

필수 조건

• Unity 2020.3 LTS 이상
• Python 3.10 이상
• 시스템에 Ollama가 설치되었습니다
• Ollama에서 가져온 LLM 모델은 다음과 같습니다.
  • ollama pull deepseek-r1:14b
  • ollama pull gemma3:12b

1단계: 편집기 스크립트 다운로드 및 설치

1. 이 저장소를 다운로드하거나 복제하세요:지엑스피1
2. Unity 프로젝트의 Assets 디렉토리에 폴더를 만듭니다.
   Assets/UnityMCPOllama
3. 복제된 저장소에서 Editor 폴더를 Unity 프로젝트로 복사합니다.
   # Copy the entire Editor folder [Repository]/Editor → Assets/UnityMCPOllama/Editor
4. 폴더 구조가 올바른지 확인하세요.
   Assets/ UnityMCPOllama/ Editor/ MCPEditorWindow.cs UnityMCPBridge.cs
5. Unity에서 스크립트를 가져와 컴파일하도록 하세요.

2단계: Python 환경 설정

1. Python 환경을 위한 폴더를 만듭니다(Unity 프로젝트 외부):
   mkdir PythonMCP cd PythonMCP
2. 복제된 저장소에서 Python 폴더를 복사합니다.
   cp -r [Repository]/Python .
3. 가상 환경을 만들고 활성화하세요.
   # Create a virtual environment python -m venv venv # Activate the virtual environment # On Windows: venv\Scripts\activate # On macOS/Linux: source venv/bin/activate
4. 종속성 설치:
   cd Python pip install -e .

3단계: Ollama 구성

1. Ollama가 시스템에 설치되어 실행 중인지 확인하세요.
2. 지원되는 모델을 가져옵니다.
   ollama pull deepseek-r1:14b ollama pull gemma3:12b
3. Ollama 서버 시작:
   ollama serve

Ollama와 함께 Unity MCP 사용

1단계: Unity Bridge 시작

1. Unity 프로젝트를 엽니다
2. MCP 창을 열려면 Window > Unity MCP 로 이동하세요.
3. Unity 브리지를 시작하려면 Start Bridge 버튼을 클릭하세요.

2단계: Python 서버 시작

1. 명령 프롬프트나 터미널을 엽니다
2. Python 환경으로 이동합니다.
   cd PythonMCP
3. 가상 환경을 활성화합니다.
   # On Windows: venv\Scripts\activate # On macOS/Linux: source venv/bin/activate
4. Python 디렉토리로 이동하여 서버를 시작합니다.
   cd Python python server.py

3단계: Ollama 설정 구성

1. Unity MCP 창에서 Ollama 구성 섹션을 찾으세요.
2. 다음 설정을 확인하거나 업데이트하세요.
   • 호스트 : localhost (기본값)
   • 포트 : 11434 (기본값)
   • 모델 : deepseek-r1:14b 또는 gemma3:12b 선택하세요
   • 온도 : 필요에 따라 조절하세요 (0.0-1.0)
3. Ollama 구성 적용을 클릭하세요

4단계: 채팅 인터페이스 사용

1. Unity MCP 창에서 채팅 인터페이스 표시 버튼을 클릭하세요.
2. 메시지 필드에 지침을 입력하세요
3. 요청을 처리하려면 보내기를 클릭하세요.

예시 프롬프트:

• "(0, 1, 0) 위치에 빨간색 큐브를 만듭니다."
• "장면에 구를 추가하고 파란색 재질을 적용합니다"
• "현재 장면의 모든 객체를 나열합니다"
• "간단한 동작 스크립트를 작성하여 큐브에 붙이세요"

연결 상태 표시기

Unity MCP 창은 각 구성 요소에 대한 상태 정보를 제공합니다.

• Python 서버 상태 : Python 서버가 실행 중인지 여부를 나타냅니다.
  • 녹색: 연결됨
  • 노란색: 연결되었지만 문제가 있음
  • 빨간색: 연결되지 않음
• Unity Bridge 상태 : Unity 소켓 서버가 실행 중인지 여부를 표시합니다.
  • 실행 중: Unity가 연결을 수신 중입니다.
  • 중지됨: Unity 소켓 서버가 활성화되지 않았습니다.
• Ollama 상태 : Ollama와의 연결 상태를 보여줍니다.
  • 연결됨: Ollama 서버에 성공적으로 연결되었습니다.
  • 연결 안 됨: Ollama에 연결할 수 없습니다.

문제 해결

일반적인 문제

1. Python 서버의 "연결되지 않음" 상태
   • Python 서버가 실행 중인지 확인하세요( python server.py )
   • Python 콘솔에서 오류를 확인하세요
   • Unity Bridge가 실행 중인지 확인하세요
2. Unity MCP 메뉴를 찾을 수 없습니다
   • 편집기 스크립트가 프로젝트에 제대로 가져왔는지 확인하세요.
   • Unity 콘솔에서 오류를 확인하세요.
   • 필요한 경우 Unity를 다시 시작하세요
3. 올라마 연결 문제
   • ollama serve 사용하여 Ollama가 실행 중인지 확인하세요.
   • 모델이 제대로 당겨졌는지 확인하세요
   • 방화벽이 포트 11434를 차단하지 않는지 확인하세요.
4. MCP 명령 실행 실패
   • 자세한 오류 메시지는 Python 콘솔에서 확인하세요.
   • Unity Bridge가 실행 중인지 확인하세요
   • 프롬프트가 명확하고 구체적인지 확인하세요.

Python 환경에 대한 명시적 설정 지침

Python 환경 설정에 문제가 발생하는 경우:

1. Python 3.10 이상을 설치하세요
2. ollama.ai 에서 Ollama를 설치하세요
3. Python 환경을 위한 전용 디렉토리를 만듭니다.
   mkdir C:\PythonMCP cd C:\PythonMCP
4. 이 저장소를 복제하거나 다운로드하여 Python 폴더를 복사하세요.
   git clone https://github.com/ZundamonnoVRChatkaisetu/unity-mcp-ollama.git copy unity-mcp-ollama\Python .
5. 가상 환경 만들기:
   python -m venv venv
6. 가상 환경을 활성화합니다.
   venv\Scripts\activate
7. 종속성 설치:
   cd Python pip install -e .
8. 서버를 실행합니다:
   python server.py

성능 고려 사항

로컬 LLM 성능은 하드웨어에 따라 달라집니다.

• deepseek-r1:14b 의 경우: 권장 최소 12GB VRAM
• gemma3:12b 의 경우: 권장 최소 10GB VRAM
• CPU 전용 작업이 가능하지만 속도가 상당히 느립니다.

기여하다

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

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다.

감사의 말

• justinpbarnett/unity-mcp 기반
• 로컬 LLM 통합을 위해 Ollama 사용