Integrations

Enables scene manipulation, object creation/editing, material management, PolyHaven asset integration, and Hyper3D Rodin model generation within Blender
Enables level creation/management, asset importing, Python code execution, and scene manipulation within Unreal Engine

언리얼-블렌더 MCP

Unreal-Blender MCP는 MCP(Machine Control Protocol) 방식을 사용하는 AI 에이전트를 통해 Blender와 Unreal Engine을 모두 제어하는 통합 서버입니다.

개요

이 프로젝트는 Blender-MCP 프레임워크를 확장하여 Unreal Engine에 대한 지원을 포함시켜 Claude와 ChatGPT와 같은 AI 에이전트가 단일 인터페이스를 통해 두 플랫폼을 동시에 제어할 수 있도록 합니다.

하위 모듈 정보

이 프로젝트에는 blender-mcp Git 하위 모듈로 포함되어 있습니다. 저장소를 복제할 때는 다음 명령을 사용하세요.

지엑스피1

특징

통합 제어 : Blender와 Unreal Engine을 모두 제어하는 단일 MCP 서버
AI 에이전트 통합 : Claude, ChatGPT 및 기타 AI 어시스턴트와 함께 작동하도록 설계되었습니다.
Blender 기능 : 다음을 포함한 모든 Blender-MCP 기능을 유지합니다.
- 장면 조작
- 객체 생성 및 편집
- 자재 관리
- PolyHaven 자산 통합
- Hyper3D Rodin 모델 생성
언리얼 엔진 기능 :
- 레벨 생성 및 관리
- 자산 가져오기
- 파이썬 코드 실행
- 장면 조작
확장 구조 : 업스트림 업데이트와의 호환성을 유지하면서 Blender 애드온과 서버를 쉽게 확장할 수 있습니다.

건축학

이 시스템은 세 가지 주요 구성 요소로 구성됩니다.

MCP 서버 : 포트 8000에서 SSE(Server-Sent Events)를 통해 AI 에이전트와 통신하는 중앙 허브
Blender Addon : 포트 8400(표준) 또는 8401(확장)의 Blender 내 소켓 서버
언리얼 플러그인 : 언리얼 엔진 내 8500 포트의 HTTP 서버

[AI Agent] <--SSE--> [MCP Server (8300)] 
                        |
                        |--HTTP--> [Blender Addon (8400)]
                        |
                        |--HTTP--> [Unreal Plugin (8500)]

확장 구조

이 프로젝트에서는 업스트림 변경 사항과의 호환성을 유지하기 위해 확장 방식을 사용합니다.

Blender Addon 확장 프로그램 : 원래 코드를 그대로 유지하면서 원래 BlenderMCPServer 확장합니다.
서버 확장 : 추가 도구와 Unreal Engine 통합을 통해 원래 서버를 향상시킵니다.
인터페이스 도구 : 확장 프로그램을 설치, 구성 및 실행하기 위한 유틸리티를 제공합니다.

이 접근 방식을 사용하면 코드 충돌 없이 원래 프로젝트에서 쉽게 업데이트할 수 있습니다.

단계별 설치 및 설정 가이드

필수 조건

Python 3.10 이상
블렌더 3.0 이상
언리얼 엔진 5.0 이상
uv 패키지 관리자(없으면 pip install uv 로 설치)

1. 저장소 복제

# Clone with submodules (recommended)
git clone --recursive https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp

# Or if you already cloned without --recursive:
git clone https://github.com/tahooki/unreal-blender-mcp.git
cd unreal-blender-mcp
git submodule update --init --recursive

2. Python 환경 설정

# Create a virtual environment and activate it
uv venv
# On Windows:
.\venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install project dependencies
uv pip install -e .

3. 블렌더 애드온 설치

다음 옵션 중 하나를 선택하세요.

옵션 A: 표준 애드온(Original blender-mcp)

블렌더 열기
편집 > 기본 설정 > 추가 기능으로 이동합니다.
"설치..." 버튼을 클릭하세요
blender-mcp/addon.py 파일을 찾아 선택하세요
"인터페이스: Blender MCP" 애드온을 활성화하세요(확인란을 선택하세요)

옵션 B: 확장 애드온(추가 기능 포함)

확장 프로그램 설치 스크립트를 실행합니다.
python -c "from src.unreal_blender_mcp.blender_addon import BlenderAddonManager; BlenderAddonManager().install_to_blender(force=True)"
블렌더 열기
편집 > 기본 설정 > 추가 기능으로 이동합니다.
"인터페이스: 확장된 블렌더 MCP" 애드온을 찾아 활성화하세요(확인란을 선택하세요)

4. 언리얼 엔진 플러그인 설치

이 프로젝트에서 UEPythonServer 폴더를 찾으세요.
전체 폴더를 Unreal 프로젝트의 Plugins 디렉토리에 복사합니다.
- 프로젝트에 Plugins 디렉토리가 없으면 하나를 만드세요.
프로젝트로 Unreal Engine을 시작하세요
메뉴에서 편집 > 플러그인으로 이동합니다.
Python Server 플러그인을 찾아 활성화하세요
메시지가 표시되면 Unreal Engine을 다시 시작하세요.

5. MCP 서버 시작

다음 옵션 중 하나를 선택하세요.

옵션 A: 표준 서버

# Make sure your virtual environment is activated
python main.py

옵션 B: 확장 서버(더 많은 기능)

# Make sure your virtual environment is activated
python run_extended_server.py

# Optional: Customize server options
python run_extended_server.py --host 127.0.0.1 --port 8080 --log-level DEBUG

6. Blender 서버 연결 활성화

Blender를 시작합니다(아직 실행 중이 아닌 경우)
3D 뷰포트에서 N 눌러 사이드바 패널을 엽니다.
적절한 탭을 선택하세요:
- "BlenderMCP"(표준 애드온을 사용하는 경우)
- "ExtBlenderMCP"(확장 애드온을 사용하는 경우)
"서버 시작" 버튼을 클릭하세요
서버가 성공적으로 시작되는지 확인하세요(콘솔 출력 확인)

7. 언리얼 엔진 연결 확인

Unreal Engine이 실행 중이고 플러그인이 활성화되어 있음
Python 서버가 자동으로 시작되어야 합니다.
출력 로그(창 > 개발자 도구 > 출력 로그)에서 메시지가 있는지 확인하세요.
이제 Unreal 플러그인이 명령을 수신할 준비가 되었습니다.

8. AI 에이전트 연결

옵션 A: 데스크톱용 Claude와 통합

Claude for Desktop 구성에 다음을 추가합니다.

{
    "mcpServers": {
        "unreal-blender": {
            "command": "uvx",
            "args": [
                "unreal-blender-mcp"
            ]
        },
        "unreal-blender-ext": {
            "command": "python",
            "args": [
                "/path/to/unreal-blender-mcp/run_extended_server.py"
            ]
        }
    }
}

/path/to/ 실제 프로젝트 경로로 바꾸세요.

옵션 B: 커서와 통합

커서 설정 열기
MCP 섹션으로 이동
다음 명령을 추가합니다.
- 표준 서버: uvx unreal-blender-mcp
- 확장 서버: python /path/to/unreal-blender-mcp/run_extended_server.py``/path/to/ 실제 프로젝트 경로로 바꾸세요.

옵션 C: 다른 AI 도구와 통합

MCP 서버와 통합하기 위해서는 AI 도구의 설명서를 참조하고 다음 내용을 확인하세요.

MCP 서버 URL: http://localhost:8000 (또는 지정된 경우 사용자 지정 포트)

9. 시스템 테스트

모든 구성 요소가 실행되면:

AI 에이전트를 사용하여 Blender와 상호 작용하려면 다음 작업을 수행해야 합니다.
- 간단한 큐브나 구를 만들어 보세요
- 객체 속성 수정
- 자료 만들기
AI 에이전트를 사용하여 다음을 요청하여 Unreal Engine과 상호 작용합니다.
- 새로운 레벨을 만드세요
- 자산 배치
- 장면 속성 수정
두 플랫폼이 함께 작동하는 보다 복잡한 작업을 시도해 보세요.

문제 해결

문제가 발생하는 경우:

모든 서버가 실행 중인지 확인하세요(MCP, Blender, Unreal)
포트 구성이 일치하는지 확인합니다(기본값: MCP의 경우 8000, Blender의 경우 8400/8401, Unreal의 경우 8500)
오류 메시지에 대한 콘솔 출력을 확인하세요.
올바른 순서로 구성 요소를 다시 시작합니다. 먼저 MCP 서버, 그 다음 Blender, 그 다음 Unreal Engine

시스템 개발 및 확장에 대한 자세한 내용은 프로젝트 문서 및 워크플로 디렉토리를 참조하세요.

비교: 표준 대 확장

특징	표준 서버	확장 서버
블렌더 컨트롤	✅	✅
비현실적인 컨트롤	✅	✅
사용자 정의 블렌더 명령	❌	✅
향상된 장면 정보	❌	✅
자동 기능 감지	❌	✅
업스트림 호환성	✅	✅

기본 기능을 원하시면 표준 서버를 선택하시고, 고급 기능을 원하시면 확장 서버를 선택하세요.

개발

자세한 개발 정보는 프로젝트 문서 및 워크플로 디렉토리를 참조하세요.

이 프로젝트를 확장하려면:

새로운 Blender 애드온 기능을 추가하려면: src/unreal_blender_mcp/blender_addon/extended_addon.py 수정하세요.
새로운 서버 도구를 추가하려면: src/unreal_blender_mcp/server_extension/extended_server.py 수정하세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

감사의 말

이 프로젝트는 Siddharth Ahuja의 blender-mcp를 기반으로 합니다.

향후 개발

향후 릴리스에서는 다음과 같은 개선 사항이 계획되어 있습니다.

구조화된 언리얼 엔진 API

현재 언리얼 엔진 통신은 주로 파이썬 코드 직접 실행에 의존합니다. 블렌더 통합과 유사한 구조화된 API를 구현하는 것이 계획되어 있습니다.

일반적인 Unreal Engine 작업에 대한 미리 정의된 함수를 만듭니다.
적절한 오류 처리 및 검증을 구현합니다.
실행 범위를 제한하여 보안을 강화하세요
운영의 안정성과 예측성 향상
구조를 추가하는 동안 이전 버전과의 호환성을 유지합니다.

이 개선을 통해 두 엔진 모두에서 더욱 일관된 사용자 경험을 제공하고 시스템의 전반적인 안정성을 향상시킬 수 있습니다. 이 개발 계획에 대한 자세한 내용은 워크플로 문서를 참조하세요.

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested