mcp-for-blender

Blender용 MCP
Blender를 모든 LLM에 연결

이전 이름은 blender-mcp — PyPI 패키지는 이제 mcp-for-blender 입니다.
기존 설정은 그대로 작동하며, 설정 변경이 필요하지 않습니다. 자세히 보기

면책 조항: 이는 서드파티 통합이며 Blender에서 제작한 것이 아닙니다

프롬프트 기반 3D 모델링, 장면 생성 및 조작 — AI가 주도합니다.

후원자

CodeRabbit
Guillermo Rauch

모든 후원자: 이 프로젝트 후원하기

빠른 시작

참고: PyPI 패키지 blender-mcp 는 이제 mcp-for-blender 입니다. 기존 설정은
그대로 작동합니다 — uvx blender-mcp 는 여전히 서버를 실행하며 설정 변경이
필요하지 않습니다 . 새로 설치하는 경우 mcp-for-blender 를 사용하세요.
무엇이, 왜 바뀌었나

명령 하나로 AI 앱과 Blender 애드온을 설정합니다:

macOS / Linux

curl -LsSf https://www.mcp-for-blender.com/install.sh | sh
Windows (PowerShell)

irm https: // www.mcp-for-blender.com / install.ps1 | iex
명령 프롬프트에서 대신 실행하려면: powershell -c "irm https://www.mcp-for-blender.com/install.ps1 | iex"

스크립트를 실행하고 싶지 않거나 Windows Defender가 차단했나요? winget으로 uv를 설치하고, 새 터미널을 연 뒤 setup을 실행하세요:

winget install -- id = astral - sh.uv - e
uvx mcp - for - blender setup
이미 uv가 있나요? 대신 uvx mcp-for-blender setup 을 실행하세요.

필요한 경우 uv를 설치하고, 머신에서 MCP 클라이언트(Claude Desktop, Claude Code, Codex, Cursor, VS Code, Devin Desktop/Windsurf, OpenCode, Antigravity)를 찾아 설정할 대상을 선택할 수 있게 해줍니다. 그런 다음 Blender 애드온을 설치하고 활성화합니다. 기존 설정은 유지됩니다: blender 항목만 추가하고, 변경하는 각 파일의 .bak 을 저장합니다.

그런 다음 AI 앱을 완전히 종료하고 다시 열고(Windows에서는 시스템 트레이에서 종료), Blender를 열고 무언가를 만들어 달라고 요청하세요. 애드온은 Blender가 열릴 때 서버를 시작합니다.

자동 설정이 작동하지 않는 경우의 수동 설정
세 단계: uv 설치 , MCP 클라이언트를 서버로 지정 , Blender 애드온 설치 .

1. uv 설치

# macOS
brew install uv

# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
winget install --id=astral-sh.uv -e
# 또는 uv의 설치 프로그램 사용
powershell -ExecutionPolicy ByPass -c " irm https://astral.sh/uv/install.ps1 | iex "

경고: uv를 설치하기 전에는 진행하지 마세요. 공식 설치 프로그램을 사용하세요 — pip install uv 가 아닙니다 .

2. MCP 서버를 클라이언트에 추가

Claude Desktop — Settings → Developer → Edit Config
{
"mcpServers" : {
"blender" : {
"command" : " uvx " ,
"args" : [ " mcp-for-blender " ]
}
}
}

Claude Code
claude mcp add blender uvx mcp-for-blender

Codex
codex mcp add blender -- uvx mcp-for-blender

Cursor / VS Code / OpenCode / Antigravity
클라이언트별 지침과 원클릭 설치 버튼은 아래 MCP 클라이언트 설정 을 참조하세요.

3. Blender 애드온 설치

uvx mcp-for-blender install-addon
그런 다음 Blender에서: Edit → Preferences → Add-ons → Interface: MCP for Blender 활성화 .

4. 연결

애드온은 Blender가 열릴 때 서버를 시작합니다. 확인하려면 3D 뷰포트에서 N 을 누르고 → MCP for Blender 탭을 여세요(실행 중이 아니면 Start MCP Server 클릭). 이제 끝입니다 — Claude에게 무언가를 만들어 달라고 요청하세요.

참고: MCP 서버 인스턴스는 하나만 실행하세요(Cursor 또는 Claude Desktop 중 하나만, 둘 다 아님).

목차

빠른 시작
기능
프리미엄
구성 요소
설치

자동 설정
사전 요구 사항
클라이언트가 uvx를 찾도록 설정
Python 버전 고정
uv 없이 설치
Docker로 실행
환경 변수

MCP 클라이언트 설정

Claude for Desktop
Codex
Cursor
Visual Studio Code
OpenCode
Antigravity

Blender 애드온 설치
업그레이드(기존 사용자)
사용법

연결 시작
Claude와 함께 사용
기능
예시 명령

영구 API 자격 증명
문제 해결
기술 세부 정보
제한 사항 및 보안 고려 사항
텔레메트리 제어
피드백
기여
면책 조항
Star 기록

기능

양방향 통신
소켓 기반 서버를 통해 Claude AI를 Blender에 연결

오브젝트 조작
Blender에서 3D 오브젝트 생성, 수정 및 삭제

머티리얼 제어
머티리얼과 색상 적용 및 수정

시각적 검증
다각도, 카메라, 와이어프레임, X-ray 및 애니메이션 스트립 뷰와 렌더를 통해 AI가 자체 작업을 검증

코드 실행
AI가 Blender Python을 직접 작성

에셋 및 모델 생성
Poly Haven 에셋, Sketchfab 모델, Poly Pizza 로우폴리 모델, 그리고 Meshy, Tripo, Hyper3D Rodin, Hunyuan3D를 통한 AI 생성 3D 모델

프리미엄
자체 API 키 없이 Meshy, Hunyuan3D, Tripo, Hyper3D Rodin으로 AI 3D 모델을 Blender에 바로 생성합니다. 자세한 내용

구성 요소
시스템은 두 가지 주요 구성 요소로 이루어집니다:

Blender 애드온 ( addon.py ) — Blender 내에 소켓 서버를 생성하여 명령을 수신하고 실행하는 Blender 애드온
MCP 서버 ( src/blender_mcp/server.py ) — Model Context Protocol을 구현하고 Blender 애드온에 연결하는 Python 서버

설치
자동 설정
가장 빠른 방법은 원라인 설치 프로그램입니다. uv를 설치하고, MCP 클라이언트를 구성하며, Blender 애드온을 설치하고 활성화합니다:

# macOS / Linux
curl -LsSf https://www.mcp-for-blender.com/install.sh | sh
# Windows (PowerShell)
irm https: // www.mcp-for-blender.com / install.ps1 | iex
이미 uv가 있나요? 대신 uvx mcp-for-blender setup 을 실행하세요. Windows에서는 winget install --id=astral-sh.uv -e 로 스크립트를 실행하지 않고 uv를 설치할 수 있습니다. 변경되는 내용은 빠른 시작 을 참조하세요. 이 섹션의 나머지 부분은 수동 설정을 다룹니다.

사전 요구 사항

Blender 3.0 이상
Python 3.10 이상
uv 패키지 관리자

플랫폼별 uv 설치
macOS

brew install uv
Windows

winget install -- id = astral - sh.uv - e
그런 다음 PATH에 반영되도록 새 터미널을 여세요. 또는 uv의 설치 프로그램을 사용하세요:

powershell - ExecutionPolicy ByPass - c " irm https://astral.sh/uv/install.ps1 | iex "
그런 다음 Windows의 사용자 경로에 uv를 추가하세요(Claude Desktop을 재시작해야 할 수 있음):

$localBin = " $ env: USERPROFILE \.local\bin "
$userPath = [ Environment ]::GetEnvironmentVariable( " Path " , " User " )
[ Environment ]::SetEnvironmentVariable( " Path " , " $userPath ; $localBin " , " User " )
Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
~/.local/bin 에 설치됩니다 — PATH에 반영되도록 새 셸을 여세요.

그 외의 경우 설치 지침은 웹사이트에 있습니다: Install uv

모든 OS에서 위의 uv 공식 설치 프로그램을 사용하세요 — pip install uv 는 uvx 명령을 생성하지 않을 수 있고, 클라이언트가 볼 수 없는 환경에 uv를 숨길 수 있으므로 사용하지 마세요.

경고: uv를 설치하기 전에는 진행하지 마세요.

클라이언트가 uvx를 찾도록 설정
GUI(Dock/시작 메뉴의 Claude Desktop, Cursor, VS Code)에서 시작된 MCP 클라이언트는 터미널의 PATH를 상속하지 않으므로, 순수한 "command": "uvx" 는 터미널에서 uvx가 작동하더라도 spawn uvx ENOENT 로 실패할 수 있습니다. 그런 경우:

uvx의 전체 경로를 찾아 — which uvx (macOS/Linux) 또는 where uvx (Windows) — "command" 로 사용하세요. 예: /opt/homebrew/bin/uvx 또는 C:\Users\<you>\.local\bin\uvx.exe .
Windows에서는 대신 감쌀 수 있습니다: "command": "cmd", "args": ["/c", "uvx", "mcp-for-blender"] .
PATH 또는 설정을 변경한 후에는 클라이언트를 완전히 종료하고 다시 실행하세요(Windows: 창만이 아니라 시스템 트레이에서 종료, macOS: Cmd + Q ).

Python 버전 고정
conda / pyenv / 버전 충돌을 피하세요.

uv는 서버를 실행할 Python을 선택합니다. conda(자동 활성화된 base), pyenv, asdf가 있는 머신 — 또는 일부 종속성의 휠이 아직 없는 최신 CPython 릴리스 — 에서는 uv가 설치를 실패하게 만드는 인터프리터를 선택할 수 있습니다. Python 3.11을 고정하고 uv 관리 인터프리터를 선호하여 PATH에 있는 것을 사용하지 않도록 하세요:

{
"mcpServers" : {
"blender" : {
"command" : " uvx " ,
"args" : [ " --python " , " 3.11 " , " mcp-for-blender " ],
"env" : { "UV_PYTHON_PREFERENCE" : " only-managed " }
}
}
}
--python 3.11 은 이 패키지의 requires-python >=3.10 을 여전히 충족하며, UV_PYTHON_PREFERENCE=only-managed 는 uv가 conda, pyenv, asdf 또는 시스템 Python을 먼저 선택하지 않도록 합니다. (저장소의 .python-version 은 기여자를 위한 힌트일 뿐이며 uvx 에는 영향을 주지 않습니다.)

수정 후에도 이전 실패한 시도가 계속 재생되면 캐시를 지우세요:

uv cache clean mcp-for-blender blender-mcp && uvx --refresh mcp-for-blender
uv 없이 설치
잠긴 머신에서는 pipx 로 uvx를 완전히 건너뛴 다음, 클라이언트를 설치된 명령으로 지정할 수 있습니다:

pipx install mcp-for-blender
pipx ensurepath # 그런 다음 셸 / 클라이언트 재시작
결과로 나온 절대 경로를 "command" 로 사용하고( which mcp-for-blender / where mcp-for-blender 로 찾기), args 는 생략하세요 .

Docker로 실행
설치하는 대신 컨테이너에서 MCP 서버를 실행할 수 있습니다. Blender 자체는 여전히 머신에서 실행됩니다 — 컨테이너는 MCP 서버만 호스팅하며, 이 서버가 Blender 애드온으로 연결합니다.

저장소 루트에서 이미지를 빌드하세요:

docker build -t mcp-for-blender .
그런 다음 MCP 클라이언트를 지정하세요( -i 플래그는 필수입니다 — 서버는 stdin/stdout으로 클라이언트와 통신합니다):

{
"mcpServers" : {
"blender" : {
"command" : " docker " ,
"args" : [ " run " , " -i " , " --rm " , " mcp-for-blender " ]
}
}
}
이미지는 기본적으로 BLENDER_HOST=host.docker.internal 로 설정되며, macOS와 Windows의 Docker Desktop에서 호스트의 Blender에 바로 연결됩니다.

Linux 에서는 host.docker.internal 이 존재하지 않고 애드온은 localhost 에서만 수신하므로, 대신 호스트 네트워킹을 사용하세요:

{
"mcpServers" : {
"blender" : {
"command" : " docker " ,
"args" : [ " run " , " -i " , " --rm " , " --network=host " , " -e " , " BLENDER_HOST=localhost " , " mcp-for-blender " ]
}
}
}
컨테이너에서 안전 모드를 활성화하려면 args 에 "-e", "BLENDER_MCP_SAFE_MODE=1" 을 추가하세요 .

환경 변수
다음 환경 변수를 사용하여 Blender 연결을 구성할 수 있습니다:

변수
기본값
설명

BLENDER_HOST
localhost
Blender 소켓 서버의 호스트 주소

BLENDER_PORT
9876
Blender 소켓 서버의 포트 번호

BLENDER_MCP_SAFE_MODE
off
1 로 설정하면 Blender에서 실행 전에 스크립트를 검증합니다(아래 참조)

BLENDER_MCP_APPS
auto
1 로 설정하면 MCP Apps를 지원한다고 알리지 않는 클라이언트에서도 인라인 뷰포트 앱을 강제로 켭니다(Codex 플러그인이 설정)

BLENDER_MCP_OPENAI_FORMS
auto
1 로 설정하면 썸네일 에셋 선택기를 강제로 켭니다(Codex 플러그인이 설정)

예:

export BLENDER_HOST= ' host.docker.internal '
export BLENDER_PORT=9876
연결을 CLI 플래그로 전달할 수도 있으며, 이는 환경 변수보다 우선합니다. 이는 여러 Blender 인스턴스를 나란히 실행할 때 유용합니다. 각 MCP 클라이언트 항목이 환경 변수 대신 일반 인수로 서로 다른 포트를 가리킬 수 있기 때문입니다:

uvx mcp-for-blender --port 9877
MCP 클라이언트 설정에서 이는 args 만 다른 두 번째 항목을 의미합니다:

{
"mcpServers" : {
"blender" : { "command" : " uvx " , "args" : [ " mcp-for-blender " ] },
"blender-b" : { "command" : " uvx " , "args" : [ " mcp-for-blender " , " --port " , " 9877 " ] }
}
}
각 인스턴스는 Blender 애드온 패널에서 일치하도록 자체 포트를 설정해야 합니다.

참고: 애드온의 소켓 서버에는 인증이나 암호화가 없으므로,
해당 포트에 접근할 수 있는 사람은 누구나 Blender 내에서 Python을 실행할 수 있습니다. 신뢰할 수 있는 네트워크가 아니라면 localhost에 유지하고, --host / BLENDER_HOST 를 원격 머신으로 직접 지정하기보다 SSH 터널을 선호하세요.

안전 모드
기본적으로 AI는 Blender에서 임의의 Python 코드를 실행할 수 있습니다. BLENDER_MCP_SAFE_MODE=1 을 설정하면 실행 전에 모든 스크립트를 검사하고 위험한 코드를 차단합니다 — 파일 직접 읽기/쓰기, 다른 프로그램 실행, 네트워크 접근, 스크립트 종료 후에도 계속 실행되는 코드 설치 등입니다. 일반적인 Blender 작업(모델링, 머티리얼, 렌더링, 저장, 가져오기/내보내기)은 여전히 작동합니다. 차단된 스크립트는 이유와 함께 AI로 반환되므로, AI가 수정된 버전으로 다시 시도할 수 있습니다.

MCP 클라이언트 설정
Claude for Desktop
설정 안내 영상을 시청하세요(uv를 이미 설치했다고 가정)

Claude → Settings → Developer → Edit Config → claude_desktop_config.json 으로 이동하여 다음을 포함하세요:

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

Claude Code
Claude Code CLI를 사용하여 MCP for Blender 서버를 추가하세요:

claude mcp add blender …