# BlenderMCP
**Claude Desktop에서 Blender 5.0.1을 실시간으로 제어하는 MCP 서버 - Windows 10 지원**
Blender addon이 소켓 서버로 동작하여 Claude Desktop과 통신합니다. 빠른 응답 속도와 실시간 상호작용이 가능합니다.
## 📋 요구사항
- **OS**: Windows 10
- **Blender**: 5.0.1 버전
- **Python**: 3.8 이상
- **Claude Desktop**: 최신 버전
## 🎯 아키텍처
```
Claude Desktop → MCP Server (Python) → Socket (localhost:9876) → Blender Addon
```
**특징**:
- ✅ 빠른 응답 (Blender를 계속 실행 상태 유지)
- ✅ 실시간 뷰포트 스크린샷
- ✅ 양방향 통신
- ✅ 여러 명령을 연속으로 빠르게 실행
## 🚀 설치 방법
### 1단계: Python 설치 확인
명령 프롬프트(CMD)에서:
```cmd
python --version
```
Python이 없다면 [Python 공식 사이트](https://www.python.org/downloads/)에서 설치하세요.
### 2단계: 저장소 클론
```cmd
git clone https://github.com/Aryeon0228/BlenderMCP.git
cd BlenderMCP
```
### 3단계: Python 패키지 설치
```cmd
pip install -r requirements.txt
```
또는:
```cmd
python -m pip install -r requirements.txt
```
### 4단계: Blender Addon 설치
#### 4-1. addon.py 파일 확인
`BlenderMCP` 폴더에 `addon.py` 파일이 있는지 확인하세요.
#### 4-2. Blender에서 addon 설치
1. **Blender 5.0.1 실행**
2. **Edit → Preferences → Add-ons**
3. **Install 버튼 클릭**
4. `addon.py` 파일을 선택하고 **Install Add-on** 클릭
5. **검색창에 "MCP" 입력**하여 "Blender MCP Server" 찾기
6. **체크박스를 활성화**하여 addon 켜기
7. **Save Preferences** 클릭 (자동 로드되도록)
#### 4-3. 서버 시작 확인
- Blender 우측 사이드바에 **"MCP"** 탭이 생깁니다
- "Server Status: Running" 이 표시되면 정상 작동 중
- Port: 9876 확인
**서버가 자동 시작되지 않으면**:
- MCP 탭에서 "Start Server" 버튼 클릭
### 5단계: Claude Desktop 설정
#### 5-1. 설정 파일 열기
Windows 탐색기 주소창에 입력:
```
%APPDATA%\Claude
```
#### 5-2. claude_desktop_config.json 생성/수정
파일이 없으면 새로 만들고, 다음 내용 추가:
```json
{
"mcpServers": {
"blender": {
"command": "python",
"args": [
"C:\\Users\\김소연\\BlenderMCP\\blender_mcp_server.py"
],
"env": {
"BLENDER_HOST": "localhost",
"BLENDER_PORT": "9876"
}
}
}
}
```
**⚠️ 중요**:
- 경로를 **실제 설치 위치**로 변경하세요
- Windows 경로는 백슬래시를 두 번(`\\`) 사용
#### 5-3. Claude Desktop 재시작
완전히 종료(작업 표시줄에서도)하고 다시 실행하세요.
## 🎨 사용 가능한 기능
### 장면 정보
- `get_scene_info` - 현재 씬의 모든 정보 조회
- `get_object_info` - 특정 객체의 상세 정보
### 객체 생성 및 조작
- `create_object` - 객체 생성 (cube, sphere, cylinder, cone, plane, torus)
- `delete_object` - 객체 삭제
- `move_object` - 객체 이동
- `scale_object` - 객체 크기 조정
- `rotate_object` - 객체 회전
### 재질 및 렌더링
- `set_material` - 재질 및 색상 설정
- `render_scene` - 씬 렌더링
- `get_viewport_screenshot` - 뷰포트 스크린샷 (실시간!)
### 고급 기능
- `execute_blender_code` - Python 코드 직접 실행 (bpy 접근)
- `save_blend_file` - .blend 파일 저장
## 💡 사용 예시
Claude Desktop에서:
```
"블렌더 씬 정보를 보여줘"
"블렌더에 빨간색 큐브를 (0, 0, 0)에 만들어줘"
"현재 블렌더 화면을 스크린샷으로 보여줘"
"Cube라는 이름의 객체를 (2, 0, 0)으로 이동해줘"
"블렌더에서 구를 만들고 파란색으로 칠해줘"
```
## 🔧 문제 해결
### "Connection Error" 발생
**원인**: Blender가 실행 중이지 않거나 addon이 비활성화됨
**해결**:
1. Blender 5.0.1 실행 확인
2. Blender에서 Edit → Preferences → Add-ons
3. "Blender MCP Server" addon 활성화 확인
4. MCP 탭에서 "Server Status: Running" 확인
### Addon이 보이지 않음
**해결**:
1. Blender를 완전히 종료하고 재실행
2. Preferences → Add-ons에서 "MCP" 검색
3. 없으면 addon.py 재설치
4. Blender 버전 확인 (5.0 이상 필요)
### MCP 서버가 연결되지 않음
**해결**:
1. Claude Desktop 완전 재시작
2. `claude_desktop_config.json` 경로 확인
3. Python 패키지 설치 확인: `pip list | findstr mcp`
4. MCP 서버 직접 실행 테스트:
```cmd
cd C:\Users\김소연\BlenderMCP
python blender_mcp_server.py
```
### 포트 충돌
다른 프로그램이 9876 포트를 사용 중이라면:
1. Blender addon에서 포트 변경 (addon.py 수정)
2. Claude Desktop 설정에서도 `BLENDER_PORT` 변경
## 📁 프로젝트 구조
```
BlenderMCP/
├── addon.py # Blender addon (소켓 서버)
├── blender_mcp_server.py # MCP 서버 (소켓 클라이언트)
├── requirements.txt # Python 의존성
├── package.json # 프로젝트 메타데이터
├── mcp_config_example.json # Claude Desktop 설정 예시
├── .env.example # 환경 변수 예시
└── README.md # 이 파일
```
## 🔄 작동 원리
1. **Blender Addon**: Blender 내부에서 소켓 서버(localhost:9876) 실행
2. **MCP Server**: Claude Desktop이 실행하는 Python 프로세스
3. **통신**: JSON 기반 명령/응답 프로토콜
4. **실행**: Blender 메인 스레드에서 안전하게 명령 실행
## ⚡ 성능 비교
### 기존 방식 (subprocess):
```
명령 실행 → Blender 시작 (10초) → 실행 → 종료
```
**총 시간**: ~10-15초/명령
### 현재 방식 (socket):
```
명령 실행 → 즉시 실행 (Blender 이미 실행 중)
```
**총 시간**: ~0.1-1초/명령
**100배 이상 빠름!** 🚀
## 🤝 기여
이슈나 PR은 언제든 환영합니다!
원본 레포지토리: [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp)
## 📄 라이선스
MIT License
## 💬 지원
문제가 발생하면:
1. GitHub Issues에 보고
2. Blender 버전 확인 (5.0.1)
3. Python 버전 확인 (3.8+)
4. 로그 확인: `%APPDATA%\Claude\logs\mcp*.log`
