blender-mcp

Blender .blend 파일을 생성하는 MCP 서버입니다. Blender에 두 가지 방식으로 접근합니다:

• Headless — 모든 호출마다 새로운 blender --background 프로세스를 시작합니다. 결정적이며 항상 사용 가능하고 파일 생성에 적합한 방식입니다.

• Live — 작은 Blender 애드온이 로컬 포트를 열어 서버가 이미 열려 있는 Blender 창을 제어할 수 있게 하며, 작업 과정을 실시간으로 볼 수 있습니다.

두 방식 모두 동일한 핸들러 코드를 실행하므로 스크립트는 어느 쪽이든 동일하게 동작합니다. 로컬 웹 UI를 통해 참조 이미지를 업로드하고 동일한 도구로 생성 작업을 실행할 수 있습니다.

요구 사항

Related MCP server: Blender MCP

설정

uv sync                                        # create .venv and install
cp .env.example .env                           # then set BLENDER_MCP_EXECUTABLE
uv run python scripts/build_addon.py --install # build + install the Blender addon

.env 파일을 생략하면 서버는 PATH와 모든 드라이브의 표준 Program Files/Blender Foundation/Blender <version> 폴더를 검색하여 가장 최신 버전을 우선 사용합니다.

라이브 브리지 활성화

애드온은 설치되어 있지만 시작하기 전까지는 비활성화 상태입니다:

1. Blender를 엽니다.

2. 3D 뷰포트에서 N을 눌러 사이드바를 표시합니다.

3. MCP 탭을 열고 Start MCP Bridge를 클릭합니다.

애드온 환경설정에서 Start listening on launch를 체크하면 매번 이 과정을 건너뛸 수 있습니다.

MCP 클라이언트 연결

.cursor/mcp.json은 이미 이 프로젝트에 서버를 등록해 놓았습니다. 모든 곳에서 사용하려면 해당 블록을 ~/.cursor/mcp.json에 복사하세요:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\Users\\josef\\Projects\\blender-mcp", "blender-mcp"]
    }
  }
}

품질 워크플로우

생성 품질은 단일 스크립트 덤프가 아닌 확인 과정에서 비롯됩니다:

1. list_references / view_reference — 먼저 가이드 이미지를 엽니다

2. studio 또는 product 템플릿으로 create_blend

3. 작은 run_script 단계로 구축; apply_material로 금속/플라스틱/고무/유리/나무 적용

4. preview_views — 다각도 EEVEE 미리보기; view_image로 참조와 비교

5. 수정 후 다시 미리보기

6. 최종 render / render_and_view (최종본은 CYCLES만 사용; 반복 작업 중에는 EEVEE 사용)

로컬 웹 UI

uv run blender-mcp-web
# open http://127.0.0.1:8765

참조 이미지를 업로드하고 프롬프트를 입력한 후 output/jobs/ 아래에서 작업을 탐색하세요.

• .env에 BLENDER_MCP_LLM_API_KEY가 있는 경우 — 사이트는 동일한 Blender 도구를 호출하는 제한된 멀티모달 에이전트를 실행합니다 (OpenAI 호환 또는 BLENDER_MCP_LLM_PROVIDER를 통한 Anthropic).

• 키가 없는 경우 — 업로드 및 작업 페이지는 여전히 작동합니다. Cursor에서 작업을 열고 MCP 에이전트에게 output/jobs/<id>/refs에서 빌드하도록 요청하세요.

도구

스크립트 작성

run_script와 create_blend의 script 인수는 bpy, mathutils, math, D (bpy.data), C (bpy.context)가 이미 바인딩된 네임스페이스에서 실행됩니다. result에 값을 할당하거나 emit(value)를 호출하여 데이터를 반환하세요.

템플릿

레이아웃

addon/blender_mcp_addon/   Blender extension + shared handlers (incl. preview_views)
src/blender_mcp/
  server.py                MCP tools
  refs.py                  reference image library
  materials.py             procedural material presets
  templates.py             starter scenes
  agent/                   bounded multimodal generation loop
  web/                     FastAPI UI (templates + static)
  headless.py / bridge.py  Blender process / live socket
scripts/                   build, install, verification
output/                    .blend files, renders, refs/, jobs/

테스트

uv run pytest -m "not blender"   # fast
uv run pytest                    # includes real Blender runs
uv run python scripts/check_server.py
uv run python scripts/verify_live_bridge.py

참고 사항 및 제한 사항

• run_script는 Blender 내에서 임의의 Python 코드를 실행합니다. 브리지는 루프백에서만 사용하세요.

• 긴 렌더링은 완료될 때까지 라이브 UI를 차단합니다.

• viewport_screenshot은 라이브 전용입니다.

• Cycles는 Blender 환경설정에서 GPU 장치를 활성화하지 않으면 CPU를 사용합니다.

• 웹 에이전트는 도구 호출과 이미지를 지원하는 멀티모달 모델이 필요합니다.

라이선스

MIT