blender-lab-mcp-client

공식 Blender.org "Blender Lab" MCP 애드온의 실제 와이어 프로토콜을 사용하는 MCP 클라이언트로, djeada/blender-mcp-server와 동일한 27가지 도구를 제공하지만 해당 프로젝트의 자체 번들 애드온 대신 blender.org/lab/mcp-server를 대상으로 합니다.

이 프로젝트가 존재하는 이유

(적어도) 두 개의 관련 없는 "Blender + MCP" 프로젝트가 우연히 이름, 기본 포트, 그리고 비슷한 제안을 공유합니다:

1. djeada/blender-mcp-server — 자체 Blender 애드온 및 Python MCP 클라이언트로 구성된 한 쌍을 제공하며, localhost:9876에서 줄바꿈으로 구분된 {"id", "command", "params"} / {"success", "result"} 프로토콜을 사용합니다.

2. 공식 Blender Lab 애드온 (blender.org/lab/mcp-server, 관리자 "Blender Authors") — 완전히 별개의 프로젝트입니다. 이것도 localhost:9876에서 수신 대기하지만 애드온 측만 제공합니다. null 바이트로 구분된 {"type": "execute", "code": ..., "strict_json": ...} 요청과 {"status": "ok"|"error", "result": ...} 응답을 사용하며, 내장된 명령어 디스패처가 없고 (bpy에 대해 원시 Python을 실행할 뿐), 모든 단일 요청 후 TCP 연결을 닫습니다.

공식 Blender Lab 애드온을 설치하지만 MCP 클라이언트를 djeada/blender-mcp-server (예: uvx blender-mcp-server 사용)로 지정하면 모든 도구 호출이 다음과 같은 오류로 실패합니다:

Extra data: line 1 column 51 (char 50)

또는 다음 호출에서:

Lost connection to Blender: Blender connection closed

이것은 불안정한 연결, 오래된 프로세스, 또는 Blender 버그가 아니라 서로 다른 두 프로토콜이 서로를 무시하고 통신하는 상황입니다. djeada의 클라이언트는 애드온이 인식하지 못하는 줄바꿈으로 끝나는 요청을 보내고, 애드온은 클라이언트를 타임아웃시키고 작은 null 바이트로 끝나는 오류를 보내며, 클라이언트의 readline()은 JSON 객체 바로 뒤의 엉뚱한 null 바이트에서 멈춥니다.

이 패키지는 동등한 bpy Python을 생성하고 이를 Blender Lab 애드온의 실제 프로토콜을 통해 전송하여 원래 27가지 MCP 도구 각각을 다시 구현합니다. 따라서 도구 이름, 매개변수 및 동작은 동일하게 유지되며, 내부의 와이어 형식만 변경됩니다.

설치

1. Blender에 공식 Blender Lab MCP 애드온을 설치하고 (편집 → 환경설정 → 애드온 → "MCP" 검색, 또는 Extensions 플랫폼을 통해) 127.0.0.1:9876에서 수신 대기 중인지 확인하세요 (애드온 환경설정 → 서버 시작).

2. 이 패키지를 설치합니다:

   git clone https://github.com/A-to-PC/blender-lab-mcp-client.git
   cd blender-lab-mcp-client
   pip install -e .

3. MCP 클라이언트를 이 패키지에 연결합니다. mcp.json 스타일 구성의 경우:

   {
     "servers": {
       "Blender": {
         "type": "stdio",
         "command": "blender-lab-mcp-client"
       }
     }
   }

   또는 설치 없이 소스에서 직접 uv로 실행합니다:

   {
     "servers": {
       "Blender": {
         "type": "stdio",
         "command": "uv",
         "args": ["run", "--project", "/absolute/path/to/blender-lab-mcp-client", "blender-lab-mcp-client"]
       }
     }
   }

도구 참조

업스트림과 동일한 27가지 도구 — 전체 표는 djeada/blender-mcp-server의 도구 참조를 참조하세요 (씬 검사, 객체 조작, 재질, 렌더링/내보내기, 히스토리, Python 실행, 비동기 작업). 이름과 매개변수는 변경되지 않았으며, 내부의 전송 방식만 다릅니다.

알려진 제한 사항

• blender_python_exec_async / blender_job_status / blender_job_cancel / blender_job_list (브리지 전송 전용)은 동기식으로 위장됩니다. 애드온의 실제 지연 작업 메커니즘은 실행된 코드 자체가 check_is_finished 호출 가능 객체를 설정해야 하는데, 임의로 제출된 코드에서 이를 일반적으로 합성하는 것은 실용적이지 않습니다. 라이브 Blender 세션에 대한 비동기 호출은 실제로 동기식으로 실행되며 즉시 "succeeded"로 보고됩니다. 진정한 장시간 작업(물리 베이크, 무거운 시뮬레이션)에는 transport="headless"를 대신 사용하세요. 해당 경로는 별도의 blender -b 백그라운드 프로세스를 실행하며 이 제한의 영향을 받지 않습니다.

• 요청당 하나의 연결. 애드온은 모든 응답 후 소켓을 닫으므로 이 클라이언트는 지속 연결을 재사용할 수 없습니다. 각 도구 호출은 새 TCP 연결을 엽니다. 이는 애드온의 실제 설계와 일치하며 클라이언트 측에서 "수정"할 수 있는 성능 단축키가 아닙니다.

• Blender 5.2 LTS 및 Blender Lab 애드온으로 테스트되었습니다. 객체/재질 도우미 코드는 표준 bpy.ops.* 호출을 사용하므로 최신 Blender 버전에서 작동해야 하지만 버전 매트릭스 전체에서 검증되지는 않았습니다.

크레딧

Adam Djellouli의 djeada/blender-mcp-server (MIT 라이선스)에서 포크했습니다. MCP 도구 표면(이름, 매개변수, 설명)과 headless.py 백그라운드 실행 전송은 변경 없이 그대로 가져왔습니다. 업스트림의 자체 번들 애드온 대신 공식 Blender Lab 애드온의 프로토콜을 대상으로 하는 server.py의 BlenderConnection과 명령-bpy-코드 변환 계층만 새로 작성되었습니다.

라이선스

MIT — LICENSE를 참조하세요.