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)에서:

python --version

Python이 없다면 Python 공식 사이트에서 설치하세요.

2단계: 저장소 클론

git clone https://github.com/Aryeon0228/BlenderMCP.git
cd BlenderMCP

3단계: Python 패키지 설치

pip install -r requirements.txt

또는:

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 생성/수정

파일이 없으면 새로 만들고, 다음 내용 추가:

{
  "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 서버 직접 실행 테스트:

   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

📄 라이선스

MIT License

💬 지원

문제가 발생하면:

1. GitHub Issues에 보고
2. Blender 버전 확인 (5.0.1)
3. Python 버전 확인 (3.8+)
4. 로그 확인: %APPDATA%\Claude\logs\mcp*.log