Blender + MCP AI 제어 환경 구축 가이드 — 무료 3D 툴을 AI로 자동 조종하는 환경 구축법

Blender 5.2 LTS에 blender-mcp 애드온과 MCP 서버를 연결해 AI 에이전트로 3D 모델링·렌더링을 자동화하는 환경 구축법이다. 4단계 설치, 명령 한 번의 동작 원리, 도구 28개 정리, 검증된 함정 5가지를 담았다.

ZCode AI 설계·제조 자동화 시리즈 — Blender 편 (설치편)

대상	AI 에이전트로 3D 모델링·렌더링을 자동화하고 싶은 메이커, 제품 개발자, 1인 개발팀
검증 환경	Windows 11 · Blender 5.2.1 LTS · blender-mcp 1.30.0 · ZCode(GLM) · NVIDIA RTX 2080 · 2026-09-08 설치 및 전 구간 테스트 완료
한 줄 요약	KiCad(회로), FreeCAD(기구)에 이어 Blender(렌더링)까지 — 전부 무료인 3종 세트로 제품 개발 파이프라인을 AI 자동화하는 환경을 만든다

이전 글에서 FreeCAD로 컨트롤러 하우징을 설계하고 제조 파일까지 뽑는 환경을 구축했다. 설계는 끝났지만, 홈페이지에 올릴 "완제품 사진"은 여전히 사람의 손이 필요한 영역이었다. 이 글은 그 마지막 조각 — Blender를 AI로 조종하는 환경을 만드는 방법을 다룬다. 설치와 연동, 동작 원리, 검증된 함정까지 실제 구축하며 발견한 내용을 모두 담았다.

1. 왜 Blender인가 — 라이선스 걱정 제로의 3D 총괄툴

Blender는 3D 모델링·소재·조명·렌더링·애니메이션을 모두 커버하는 오픈소스다. 상업적 사용료가 0원이고, 만든 결과물을 제품 홈페이지·광고에 쓰는 것도 자유다. AI 자동화 관점에서 중요한 성질은 세 가지다.

1. Python 내장 — Blender의 모든 기능이 Python API(bpy)로 노출된다. UI에서 하는 일은 전부 스크립트로 할 수 있다.
2. 소켓 서버를 만들 수 있다 — 애드온 형태로 외부 프로그램과 통신하는 채널을 열 수 있다. MCP 연동의 핵심 통로다.
3. GPU 렌더러(Cycles) — 요즘 게이밍 GPU가 있으면 제품 사진 한 장을 1~2분에 뽑는다.

이 세 가지를 연결해 주는 것이 blender-mcp(ahujasid) 프로젝트다. PyPI에 MCP 서버가 올라와 있고, Blender 쪽 애드온 소스는 GitHub에서 받는다.

2. 전체 구조 — AI는 이렇게 Blender를 조종한다

FreeCAD 편에서 소개한 구조와 같은 계보다. AI 클라이언트와 3D 프로그램 사이에 MCP 서버가 서고, 프로그램 안에는 애드온이 소켓 서버로 대기하는 3단 구조다.

flowchart LR
    A["사용자 명령 자연어"] --> B["ZCode AI 에이전트 GLM"]
    B -->|"MCP stdio 줄단위 JSON-RPC"| C["blender-mcp 서버 uvx · 도구 28개"]
    C -->|"TCP 소켓 포트 9876"| D["MCP for Blender 애드온 소켓 서버"]
    D -->|"bpy 실행"| E["Blender 5.2 씬 모델링 · 소재 · 조명"]
    E -->|"Cycles GPU 렌더 OptiX"| F["완성 이미지 PNG · MP4"]

핵심은 Blender가 실행 중이어야 AI가 일할 수 있다는 점이다. FreeCAD 편의 auto_start_rpc처럼, 이번 구축에서는 Blender를 켜면 소켓 서버가 자동으로 열리는 보조 애드온을 직접 만들어 해결했다. 사용자는 그냥 Blender를 켜기만 하면 된다.

3. 설치하기 — 4단계 15분

1단계. Blender 5.2 LTS 설치

blender.org에서 내려받아 설치한다. 2026년 9월 기준 최신 안정판은 5.2.1 LTS(2028년 7월까지 지원)다. 이미 5.2.0이 설치돼 있다면 MSI 하나로 무인 업데이트할 수 있다.

:: 무인 업데이트 (관리자 권한 필요)
msiexec /i blender-5.2.1-windows-x64.msi /qn /norestart

주의: 5.2.0 → 5.2.1 업데이트 직후 애드온 활성화 상태가 초기화되는 것을 확인했다. 업데이트 후 아래 명령으로 다시 켜 주자.

:: 애드온 활성화 + 설정 저장 (한 줄)
blender.exe --background --python-expr "import addon_utils; addon_utils.enable('blender_mcp', default_set=True, persistent=True)"

2단계. MCP 애드온 설치

GitHub ahujasid/blender-mcp 저장소의 addon.py(v1.6)를 내려받아 Blender 사용자 폴더에 넣는다. Blender 4.x부터 도입된 확장(Extensions) 방식이 아니라 레거시 애드온 방식으로 넣어도 5.x에서 정상 동작한다.

%APPDATA%\Blender Foundation\Blender\5.2\scripts\addons\blender_mcp\__init__.py

파일을 넣은 뒤 위 1단계의 활성화 명령을 실행하면, Blender의 N패널 → MCP for Blender 탭이 생긴다.

3단계. 자동시작 보조 애드온 (권장)

수동 설치 경로에서는 Blender를 켤 때마다 "Connect to MCP server" 버튼을 눌러야 한다. 버튼 누르는 일조차 AI에게 맡기자. scripts/addons/blender_mcp_autostart\__init__.py로 아래 애드온을 넣으면 Blender 시작 2초 뒤 포트 9876이 자동으로 열린다.

bl_info = {"name": "Blender MCP Auto-Start", "version": (1, 0),
           "blender": (3, 0, 0), "category": "Interface"}
import bpy, addon_utils

def _start():
    try:
        import blender_mcp
        scene = bpy.context.scene
        if not getattr(scene, "blendermcp_server_running", False):
            if not getattr(bpy.types, "blendermcp_server", None):
                bpy.types.blendermcp_server = blender_mcp.BlenderMCPServer(
                    port=scene.blendermcp_port)
            bpy.types.blendermcp_server.start()
            scene.blendermcp_server_running = True
    except Exception as e:
        print("[mcp-autostart]", e)

def register():
    if not addon_utils.check("blender_mcp")[1]:
        addon_utils.enable("blender_mcp", default_set=True, persistent=True)
    bpy.app.timers.register(_start, first_interval=2.0, persistent=True)

타이머 콜백에서는 bpy.ops 컨텍스트가 불안정하므로, 공식 "Connect to Claude" 버튼이 하던 일을 서버 클래스 직접 인스턴스화로 대신했다. 이것이 이 환경에서 유일하게 직접 작성한 코드다.

4단계. ZCode 워크스페이스 등록

워크스페이스 폴더의 .zcode/config.json에 서버를 등록한다. FreeCAD 편과 같은 형식이다.

{
  "mcp": {
    "servers": {
      "blender": { "command": "uvx", "args": ["blender-mcp"] }
    }
  }
}

이 폴더에서 새 ZCode 세션을 열면 도구 접두사 mcp__blender__* 28개가 자동으로 연결된다. uvx가 없다면 pip install uv로 먼저 설치한다.

설치가 끝나면 Blender는 이런 모습이 된다. 뷰포트에는 AI가 만든 제품이 실시간 렌더로 돌아가고, 오른쪽 아웃라이너에는 AI가 배치한 조명과 카메라가 정리되어 있다.

구축 완료 후 실제 작업 화면. 제품 렌더링에 쓰인 조명 5개·카메라·바닥이 모두 AI가 만든 것이다.

flowchart TD
    S1["1. Blender 5.2 LTS 설치"] --> S2["2. blender_mcp 애드온 설치 scripts/addons 폴더에 넣고 활성화"]
    S2 --> S3["3. 자동시작 애드온 등록 Blender 켜면 9876 자동 오픈"]
    S3 --> S4["4. ZCode 워크스페이스 등록 .zcode/config.json"]
    S4 --> Q{"Blender 실행 중?"}
    Q -->|"예"| OK["mcp__blender__ 도구 28개 사용 가능"]
    Q -->|"아니오"| RUN["Blender를 먼저 실행"]
    RUN --> OK

4. 동작 원리 — 명령 한 번의 여정

"씬에 뭐 있는지 알려줘"라는 말 한마디가 실제로는 이렇게 흘러간다.

sequenceDiagram
    participant U as 사용자
    participant Z as ZCode GLM
    participant M as blender-mcp
    participant B as Blender 애드온
    U->>Z: 씬 객체 목록 알려줘
    Z->>M: tools/call · get_scene_info
    Note over M: user_prompt 인자 필수 (1.30.0~)
    M->>B: 소켓 명령 전송 (9876)
    B->>B: Blender 메인 스레드에서 bpy 실행
    B-->>M: 씬 정보 JSON
    M-->>Z: 도구 응답 (content 배열)
    Z-->>U: Cube·Light·Camera 등 3개 객체가 있습니다

렌더링 같은 무거운 작업도 같은 길을 간다. execute_blender_code 도구에 Python 코드를 실어 보내면 Blender가 자기 메인 스레드에서 그대로 실행한다. 즉 AI에게 가능한 일의 상한선 = Blender Python API의 상한선이다.

5. 도구 28개 — 무엇이 가능한가

에셋 도구가 특히 유용하다. "제품 옆에 나무 테이블 놓고 스튜디오 조명 느낌으로"라고 하면 AI가 PolyHaven에서 텍스처와 HDRI를 받아 씬을 꾸민다. 전부 CC0 라이선스라 상업 사용도 문제없다.

뷰포트를 렌더드 셰이딩으로 전환해 두면, 최종 렌더와 거의 같은 화면을 실시간으로 볼 수 있다. AI가 소재를 입히고 조명을 움직일 때마다 화면이 같이 바뀌므로, 작업을 지켜보는 재미도 상당하다.

뷰포트 렌더드 모드. 별도 렌더 버튼 없이 GPU가 이 화면을 계속 그려준다.

6. 구축하며 발견한 함정 Top 5

직접 부딪혀 확인한 것만 발췌한다. 전체 목록은 워크스페이스 AGENTS.md에 기록해 뒀다.

5번이 특히 아쉬운 부분이다. 창을 다른 모니터로 옮기는 것은 전혀 문제없고, 실시간 렌더 뷰도 그 모니터에서 잘 돌아간다. 최소화만은 피하자.

7. 마치며 — 3종 세트가 완성됐다

KiCad(회로·PCB) → FreeCAD(기구·제조파일) → Blender(렌더링·시각화). 전부 무료인 세 개의 툴이 AI 에이전트 하나로 연결됐다. 설치 자체는 15분이면 끝나지만, 진짜 값어치는 이것으로 "설계도가 아니라 완제품 사진"을 명령으로 뽑아낼 수 있다는 점이다. 그 과정은 다음 글에서 실제 사례로 확인할 수 있다.

다음 편: 컨트롤러 하우징, FreeCAD 모델이 완제품 광고컷으로 — AI 3D 렌더링 자동화 사용기
FreeCAD에서 만든 하우징에 AI가 소재를 입히고, 조명을 설치하고, 스튜디오 컷 2장을 뽑아내는 전 과정 — 그리고 중간에 두 번 실패한 이야기까지.