Claude Code 터미널에서 "던전 장면에 용 한 마리를 넣어줘" 같은 자연어 요청만으로 Blender가 실제로 장면을 만들게 하고 싶다면, MCP(Model Context Protocol — Claude 같은 AI가 외부 프로그램과 대화할 수 있게 해 주는 연결 규약)를 이용한 연동이 방법입니다. 이 글은 uv 설치부터 Blender 애드온 연결, Claude Code에 서버를 등록하는 명령어까지 순서대로 따라 하면 실제로 동작하는 연동을 완성할 수 있도록 정리했습니다. 준비된 환경이라면 15~20분 정도 걸립니다.
이 글로 무엇을 할 수 있나요?
이 글을 따라 하면 Claude Code 터미널에 자연어로 요청하는 것만으로 Blender가 장면·객체·머티리얼을 만들고 수정하는 것을 확인할 수 있습니다. 이 연동에서 쓸 수 있는 대표 기능은 다음과 같습니다.
- 장면·객체 정보 조회 및 조작 — 현재 장면 상태를 읽고, 도형을 생성·수정·삭제합니다.
- 머티리얼 적용·생성 — "이 자동차를 빨간 메탈릭으로 바꿔줘" 같은 요청을 처리합니다.
- Python 코드 실행 — Blender 내부 스크립팅 API를 직접 실행합니다(뒤에서 다룰 보안 주의사항과 관련됩니다).
- GLB·FBX 내보내기 — 완성한 장면을 다른 프로그램에서 쓸 수 있는 파일로 저장합니다.
- 외부 에셋 가져오기 — Poly Haven, Sketchfab, Poly Pizza 등에서 모델을 내려받아 장면에 배치합니다.
시작 전 준비물
시작 전 필요한 것은 Blender, uv 패키지 매니저, Claude Code 세 가지입니다.
- Blender 3.0 이상 — 이미 설치돼 있고 실행할 수 있는 상태여야 합니다.
- Python 3.10 이상 — 뒤에서 설치할 uv가 있으면 Python을 따로 챙기지 않아도 uvx가 알아서 처리해 줍니다.
- uv — Python 패키지·실행 도구(pip install uv가 아니라 공식 설치 스크립트로 설치해야 합니다.)
- Claude Code 설치 및 로그인 상태 — 터미널에서
claude명령이 실행되는지 미리 확인하세요.
uv는 운영체제별로 아래 명령으로 설치합니다.
| 운영체제 | 설치 명령 |
|---|---|
| macOS | brew install uv |
| Windows(PowerShell) | irm https://astral.sh/uv/install.ps1 | iex |
| Linux | curl -LsSf https://astral.sh/uv/install.sh | sh |
용어 빠른 풀이
- MCP(Model Context Protocol) — Claude 같은 AI가 Blender 같은 외부 프로그램의 기능을 표준화된 방식으로 호출할 수 있게 해 주는 연결 규약입니다.
- uv / uvx — Python 패키지·실행 관리 도구입니다.
uvx는 별도 설치 과정 없이 도구를 바로 내려받아 실행해 주는 명령입니다. - 소켓 서버 — 프로그램 간에 데이터를 주고받는 통신 창구입니다. 여기서는 Blender 애드온이 자신의 컴퓨터(로컬호스트) 안에서 이 서버를 열어 MCP 서버와 통신합니다.
- 애드온(add-on) — Blender에 기능을 추가하는 확장 프로그램입니다.
Blender 연동 방식 두 가지
Blender를 Claude와 연결하는 방법은 Blender 재단이 Blender Lab에서 배포하는 공식 MCP 서버와, 커뮤니티가 만든 MCP 서버(mcp-for-blender, 옛 이름 blender-mcp) 두 가지가 있습니다. 이 글은 설치가 간단하고 Blender 3.0부터 쓸 수 있는 커뮤니티 서버를 기준으로 안내합니다. 공식 서버도 표준 MCP 서버라 Claude Code에 붙일 수는 있지만, 공식 페이지 기준 Blender 5.1 이상이 필요하고 소스 설치 안내가 llama.cpp 중심이라 초보자에게는 진입 장벽이 있습니다(2026년 9월 17일 확인).
| 구분 | 공식 Blender Lab MCP 서버 | 커뮤니티 MCP 서버(mcp-for-blender) |
|---|---|---|
| 지원 클라이언트 | 표준 MCP 클라이언트 전반(.mcpb 번들 지원 클라이언트 또는 소스 설치) | Claude Code·Claude Desktop 등 MCP 클라이언트 전반 |
| Blender 최소 버전 | 5.1 이상(공식 페이지) | 3.0 이상(프로젝트 README) |
| 설치 방식 | Blender Lab 저장소 추가 후 애드온 설치(드래그 두 번) 또는 ZIP 설치 + MCP 서버 별도 설치 | uv/uvx로 서버 실행 + install-addon으로 애드온 설치 |
| 만든 주체 | Blender 재단(Blender Lab) | 오픈소스 커뮤니티 프로젝트(Blender와 무관한 서드파티) |
참고로 Claude Desktop의 커넥터 목록에도 "Blender" 항목이 있습니다(2026년 4월 28일 Anthropic이 발표한 창작 도구 커넥터 9종 중 하나). 이 경로는 Claude Desktop 앱 전용이며, 요구 Blender 버전은 Claude 화면과 Blender 공식 페이지의 표기가 달라(4.2 대 5.1) 최신 버전을 쓰는 편이 안전합니다.
단계별 연결 과정
Blender와 Claude Code를 연결하려면 uv 설치, Blender 애드온 설치, Blender에서 서버 시작, Claude Code에 서버 등록, 연결 확인까지 다섯 단계를 거칩니다.
1단계 — uv 설치
위 표의 명령을 터미널에 붙여넣어 실행합니다.
curl -LsSf https://astral.sh/uv/install.sh | sh설치가 끝나면 터미널에 uv --version을 입력했을 때 버전 번호가 출력되면 성공입니다.
2단계 — Blender에 MCP 애드온 설치
터미널에서 아래 명령을 실행하면 필요한 애드온 파일을 Blender에 자동으로 설치해 줍니다.
uvx mcp-for-blender install-addon자동 설치가 안 되면 Blender를 열고 Edit → Preferences → Add-ons에서 "MCP for Blender"를 검색해 수동으로 설치·활성화할 수도 있습니다(설치 파일은 프로젝트의 GitHub 저장소에서 받습니다). Preferences의 Add-ons 목록에 항목이 체크 표시로 나타나면 성공입니다.
3단계 — Blender에서 서버 시작
Blender 3D 뷰포트에서 N 키를 눌러 오른쪽 사이드바를 열고, MCP 관련 탭을 찾아 연결(서버 시작)에 해당하는 버튼을 눌러 소켓 서버를 켭니다(정확한 버튼 문구는 설치한 애드온 버전에 따라 다를 수 있으니 화면에 표시된 안내를 확인하세요). 탭에 "연결됨" 또는 이와 비슷한 상태 표시가 뜨면 성공입니다.
주의 — 이 단계 이후 Claude가 Blender 파일을 직접 수정할 수 있게 됩니다. 서버를 켜기 전에 작업 중이던 .blend 파일을 저장해 두세요.
4단계 — Claude Code에 MCP 서버 등록
Blender가 아니라 터미널에서(Claude Code 세션 안이 아니라) 아래 명령으로 서버를 등록합니다.
claude mcp add blender uvx mcp-for-blenderAdded stdio MCP server blender...처럼 등록을 확인하는 메시지가 뜨면 성공입니다. 기본값은 현재 프로젝트에서만 적용되는 local 범위이며, 모든 프로젝트에서 쓰려면 --scope user 옵션을 붙여 다시 등록하면 됩니다.
5단계 — 연결 확인
claude mcp list목록에서 blender 서버 옆에 ✔ Connected가 표시되면 연결이 완료된 것입니다. ✘ Failed to connect가 보이면 3단계에서 Blender 쪽 서버를 켜지 않았을 가능성이 크니 Blender 창을 확인하세요.
실제로 사용해보기 — 예시 프롬프트
연결이 끝났다면 Claude Code 세션에서 아래처럼 자연어로 요청해 동작을 확인할 수 있습니다.
- "던전 배경에 용이 있는 로우폴리 장면을 만들어줘"
- "이 자동차를 빨간색 메탈릭 머티리얼로 바꿔줘"
- "카메라를 장면 쪽으로 향하게 하고 아이소메트릭 구도로 맞춰줘"
Claude Code 출력에서 도구 호출이 blender 서버 이름으로 표시되면 실제로 이 연동을 거쳐 처리된 것입니다.
자주 막히는 지점과 해결
연결·응답 관련 문제 대부분은 아래 표의 원인 중 하나에 해당합니다.
| 증상 | 원인 | 조치 |
|---|---|---|
claude mcp list에서 Failed to connect | Blender에서 서버를 아직 켜지 않았거나 Blender가 꺼져 있음 | Blender를 실행하고 N 패널에서 서버를 켠 뒤 다시 확인 |
| 연결은 되지만 도구 목록이 비어 있음 | 애드온 버전과 서버 버전이 안 맞음 | 애드온을 최신 버전으로 재설치하고 Blender 재시작 |
| 복잡한 요청에서 시간 초과(timeout) 오류 | 한 번에 처리하기엔 요청 범위가 너무 큼 | 요청을 더 작은 단계로 나눠서 순차적으로 지시 |
| Poly Haven·Sketchfab 등 외부 에셋 다운로드 실패 | 외부 사이트 접속 문제 | 네트워크 상태 확인 후 재시도 |
보안 주의사항
이 연동에서 가장 주의할 점은 Claude가 Blender 안에서 임의의 Python 코드를 실행할 수 있다는 것입니다.
- 임의 코드 실행 — 장면 조작용 도구 중에는 Blender 내부 Python 코드를 직접 실행하는 기능이 있어, 강력한 만큼 의도치 않은 결과를 낼 수도 있습니다.
- Blender 공식 경고 — Blender Lab의 MCP 서버 페이지는 "LLM이 생성한 코드를 아무 보호 장치 없이 실행하므로 데이터가 삭제되거나 외부로 전송될 수 있다"며 가상 머신이나 민감한 정보가 없는 시스템에서 쓰라고 권고합니다. 커뮤니티 서버도 같은 구조이므로 동일하게 적용됩니다.
- 작업 저장 습관화 — 서버를 켜고 요청을 보내기 전에 항상 .blend 파일을 저장해 두세요.
- 안전 모드(SAFE_MODE) — 커뮤니티 서버는 환경 변수
BLENDER_MCP_SAFE_MODE=1을 켜면 실행 전에 스크립트를 검사해 파일 직접 읽기·쓰기, 외부 프로그램 실행, 네트워크 접근 같은 위험 동작을 차단합니다(README 기준). 일반 모델링·머티리얼·렌더·저장·가져오기/내보내기는 그대로 동작합니다. - 로컬호스트 범위 유지 — 이 소켓 서버는 별도 인증 없이 동작하므로, 같은 컴퓨터 안에서만 쓰고 외부 네트워크에 노출하지 않는 것이 안전합니다.
응용 — 다음 단계
여기서 익힌 add → 확인(list) → 사용 흐름은 Blender뿐 아니라 다른 MCP 서버를 Claude Code에 연결할 때도 그대로 적용됩니다. 여러 프로젝트에서 반복해 쓰고 싶다면 4단계 명령에 --scope user를 붙여 등록하고, 팀과 설정을 공유하고 싶다면 --scope project로 등록해 .mcp.json 파일을 저장소에 커밋하면 됩니다.
자주 묻는 질문
Q. Blender MCP는 Claude Code에서만 쓸 수 있나요?
아니요, 이 글에서 다룬 커뮤니티 MCP 서버는 Claude Code뿐 아니라 Claude Desktop 등 다른 MCP 클라이언트에서도 쓸 수 있습니다. Blender 재단의 공식 MCP 서버(Blender 5.1 이상) 역시 표준 MCP 서버라 클라이언트를 가리지 않습니다. Claude Desktop 앱의 커넥터 목록에 있는 "Blender" 항목만 Desktop 전용입니다.
Q. execute_blender_code 같은 도구를 쓰면 위험한가요?
임의의 Python 코드를 실행하는 기능이라 주의가 필요합니다. 항상 작업을 저장한 뒤 사용하고, 결과를 확인하며 진행하는 것이 안전합니다.
Q. Claude Code에 등록한 서버는 다른 프로젝트에서도 보이나요?
기본값(local 범위)은 등록한 프로젝트에서만 적용됩니다. 모든 프로젝트에서 쓰려면 --scope user 옵션으로 다시 등록해야 합니다.
Q. Blender를 껐다 켜면 설정을 다시 해야 하나요?
애드온 설치와 Claude Code 서버 등록은 한 번만 하면 유지되지만, Blender 안의 소켓 서버는 Blender를 새로 실행할 때마다 N 패널에서 다시 켜야 합니다.
uv 설치부터 claude mcp list 확인까지 다섯 단계만 거치면, Claude Code 터미널에서 자연어로 Blender 작업을 지시하는 워크플로를 그대로 쓸 수 있습니다.