Blender MCP (MCP for Blender)
- 추천0
- GitHub 별35K
- 디자인라이선스MIT
AI가 Blender를 직접 다뤄 3D 모델링 · 장면 구성 · 재질 · 에셋 가져오기까지 하게 하는 MCP 서버. MIT
설치 방법은 설치 탭에 정리했어요.
설명
예전 이름은 blender-mcp이며, PyPI 패키지는 이제 mcp-for-blender입니다.
기존 설정은 그대로 동작하며 설정을 바꿀 필요가 없습니다. 자세히 보기
면책: 이 프로젝트는 서드파티 연동이며 Blender가 만든 것이 아닙니다.
프롬프트로 하는 3D 모델링, 장면 만들기, 조작을 AI가 해 줍니다.
후원해 주신 분들
모든 후원자: 이 프로젝트 후원하기
빠른 시작
💡 참고 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를 설치하고 새 터미널을 연 다음 설정을 실행하세요.
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
# or, with uv's installer
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 자격 증명
- 문제 해결
- 기술 세부 사항
- 한계와 보안 고려 사항
- 원격 측정 제어
- 피드백
- 기여하기
- 면책 조항
- 별 기록
기능
| 양방향 통신 | 소켓 기반 서버로 Claude AI를 Blender에 연결합니다 |
| 객체 조작 | Blender에서 3D 객체를 만들고, 고치고, 지웁니다 |
| 재질 제어 | 재질과 색을 적용하고 고칩니다 |
| 시각 검증 | 여러 각도, 카메라, 와이어프레임, 엑스레이, 애니메이션 스트립 보기와 렌더로 AI가 자기 작업을 직접 확인합니다 |
| 코드 실행 | AI가 Blender 파이썬을 직접 씁니다 |
| 에셋과 모델 생성 | Poly Haven 에셋, Sketchfab 모델, Poly Pizza 로우폴리 모델, Meshy · Tripo · Hyper3D Rodin · Hunyuan3D로 만든 AI 3D 모델, World Labs로 만든 가우시안 스플랫 월드 전체 |
프리미엄
자신의 API 키를 가져오지 않고도 AI 3D 모델(Meshy, Hunyuan3D, Tripo, Hyper3D Rodin)과 World Labs 월드를 Blender로 바로 생성합니다. 자세히 보기
구성 요소
시스템은 두 가지 주요 구성 요소로 이루어져 있습니다.
- Blender 애드온(
addon.py) — Blender 안에 소켓 서버를 만들어 명령을 받고 실행하는 Blender 애드온 - MCP 서버(
src/blender_mcp/server.py) — Model Context Protocol을 구현하고 Blender 애드온에 연결하는 파이썬 서버
설치
자동 설정
가장 빠른 방법은 한 줄 설치 프로그램입니다. 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에 잡히게 하세요.
그 밖의 설치 안내는 uv 웹사이트에 있습니다: uv 설치
어느 OS에서든 위의 uv 공식 설치 프로그램을 쓰세요. pip install uv는 쓰지 마세요. uvx 명령이 만들어지지 않을 수 있고, 클라이언트가 볼 수 없는 환경 안에 uv가 숨어 버릴 수 있습니다.
⚠️ 경고 uv를 설치하기 전에는 진행하지 마세요.
클라이언트가 uvx를 찾게 하기
GUI에서 시작한 MCP 클라이언트(Claude Desktop, Cursor, Dock/시작 메뉴에서 연 VS Code)는 터미널의 PATH를 물려받지 않으므로, uvx가 터미널에서는 잘 되는데도 "command": "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을 고정하고 PATH에 있는 아무 것이나 쓰지 않도록 uv가 관리하는 인터프리터를 우선하게 하세요.
{
"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 # then restart your shell / client
나온 절대 경로(which mcp-for-blender / where mcp-for-blender로 찾습니다)를 "command"로 쓰고 args는 생략하세요.
Docker로 실행
MCP 서버를 설치하는 대신 컨테이너에서 실행할 수 있습니다. Blender 자체는 내 컴퓨터에서 계속 실행되며, 컨테이너는 MCP 서버만 호스팅하고 Blender 애드온에 밖으로 연결합니다.
저장소 루트에서 이미지를 빌드합니다.
docker build -t mcp-for-blender .
그런 다음 MCP 클라이언트가 그것을 가리키게 합니다(서버가 stdin/stdout으로 클라이언트와 통신하므로 -i 플래그가 필수입니다).
{
"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 | 꺼짐 | 1로 두면 Blender에서 스크립트가 실행되기 전에 검증합니다(아래 참고) |
BLENDER_MCP_APPS | 자동 | MCP Apps를 지원하지만 알리지 않는 클라이언트에서 인라인 뷰포트 앱을 강제로 켜려면 1로 둡니다(Codex 플러그인이 설정합니다) |
BLENDER_MCP_OPENAI_FORMS | 자동 | 썸네일 에셋 선택기를 강제로 켜려면 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 안에서 파이썬을 실행할 수 있습니다. 신뢰할 수 있는 네트워크가 아니면
localhost에만 두고,--host/BLENDER_HOST를 원격 기기에 직접 가리키게 하기보다 SSH 터널을 쓰세요.
안전 모드
기본으로 AI는 Blender에서 어떤 파이썬 코드든 실행할 수 있습니다. BLENDER_MCP_SAFE_MODE=1로 두면 모든 스크립트를 실행 전에 검사해 위험한 코드를 막습니다. 파일을 직접 읽고 쓰기, 다른 프로그램 실행, 네트워크 접근, 스크립트가 끝난 뒤에도 계속 도는 코드 설치 같은 것들입니다. 일반적인 Blender 작업(모델링, 재질, 렌더링, 저장, 가져오기/내보내기)은 여전히 됩니다. 막힌 스크립트는 이유와 함께 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 uvx mcp-for-blender
Codex
Codex CLI, 데스크톱 앱, IDE 확장은 모두 같은 설정 파일(~/.codex/config.toml)을 쓰므로 서버를 한 번 설정하면 셋 모두에 적용됩니다.
Codex 플러그인(권장)
플러그인은 채팅 안에 라이브 뷰포트를 넣어 주고(객체를 클릭하면 다음 메시지에 첨부됩니다), Poly Haven · Sketchfab · Poly Pizza용 썸네일 선택기와 장면 객체 · 재질 · 컬렉션에 대한 @ 멘션을 더합니다. 아직 Codex 플러그인 디렉터리에는 없으므로 이 저장소에서 추가하세요.
git clone https://github.com/ahujasid/blender-mcp.git
codex plugin marketplace add ./blender-mcp/integrations/codex
그런 다음 Codex를 다시 시작하고, 플러그인 디렉터리에서 MCP for Blender를 설치한 뒤, 채팅에서 MCP for Blender를 쓰라고 요청하세요. 실행되면 뷰포트가 대화 옆 사이드 패널에 열립니다.

일반 MCP 서버
Codex CLI로 서버를 등록합니다.
codex mcp add blender -- uvx mcp-for-blender
또는 ~/.codex/config.toml(또는 $CODEX_HOME/config.toml)에 직접 추가하세요.
[mcp_servers.blender]
command = "uvx"
args = ["mcp-for-blender"]
또는 Codex 데스크톱 앱에서: Settings → MCP servers → Add server → 이름을 blender로 짓고 STDIO를 고른 뒤, 명령으로 uvx mcp-for-blender를 입력하고 Save한 다음 다시 시작하세요. 앱이 uvx를 찾지 못하면 전체 경로를 대신 쓰세요. 클라이언트가 uvx를 찾게 하기를 보세요.
codex mcp list로 등록됐는지 확인하세요. blender 서버가 enabled로 보여야 합니다. 도구는 다음에 Codex를 시작할 때부터 쓸 수 있습니다.
환경 변수(예: 기본값이 아닌 Blender 호스트/포트)를 설정하려면 codex mcp add에 --env KEY=VALUE 플래그를 넘기거나 설정 파일에 추가하세요.
[mcp_servers.blender]
command = "uvx"
args = ["mcp-for-blender"]
env = { BLENDER_HOST = "localhost", BLENDER_PORT = "9876" }
Cursor
macOS — Settings → MCP로 가서 다음을 붙여 넣으세요.
- 전역 서버로 쓰려면 "add new global MCP server" 버튼을 눌러 붙여 넣습니다
- 프로젝트별 서버로 쓰려면 프로젝트 루트에
.cursor/mcp.json을 만들어 붙여 넣습니다
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": [
"mcp-for-blender"
]
}
}
}
Windows — Settings → MCP → Add Server로 가서 다음 설정으로 새 서버를 추가하세요.
{
"mcpServers": {
"blender": {
"command": "cmd",
"args": [
"/c",
"uvx",
"mcp-for-blender"
]
}
}
}
💡 참고 MCP 서버는 Cursor나 Claude Desktop 중 한 곳에서만 하나 실행하세요. 둘 다 실행하면 안 됩니다.
Visual Studio Code
요구 사항: 진행하기 전에 Visual Studio Code가 설치되어 있어야 합니다.
OpenCode
{
"mcp": {
"blender-mcp": {
"type": "local",
"command": ["uvx", "mcp-for-blender"],
"enabled": true,
"environment": {
"BLENDER_HOST": "localhost",
"BLENDER_PORT": "9876"
}
}
}
}
Antigravity
{
"mcpServers": {
"blender-mcp": {
"command": "uvx",
"args": ["mcp-for-blender"],
"env": {
"BLENDER_HOST": "localhost",
"BLENDER_PORT": "9876"
}
}
}
}
Blender 애드온 설치
uvx mcp-for-blender setup(빠른 시작 참고)이 애드온 켜기까지 이 모든 것을 해 줍니다. 아래 단계는 직접 할 때의 방법입니다.
1. 권장 — 터미널에서 다음을 실행하세요.
uvx mcp-for-blender install-addon
이 명령은 애드온을 Blender 애드온 폴더에 blender_mcp.py로 복사합니다. 어디에 썼는지 출력하며, 바꾼 파일은 .bak로 남깁니다.
선택 사항:
uvx mcp-for-blender addon-paths는 감지된 Blender 애드온 폴더를 나열합니다. 대상 위치는BLENDERMCP_ADDONS_DIR=/path/to/scripts/addons로 바꿀 수 있습니다.
2. Blender를 엽니다
3. Edit → Preferences → Add-ons로 갑니다
4. Interface: MCP for Blender를 켭니다("MCP for Blender"를 검색하세요). 아직 보이지 않으면 **Install…**을 눌러 복사된 blender_mcp.py / addon.py를 고르거나 Blender를 다시 시작하세요.
5. 수동 대안 — 위 명령이 Blender 설치를 찾지 못하거나 직접 하고 싶다면: 이 저장소에서 addon.py를 내려받아 → Blender에서 Edit → Preferences → Add-ons → Install… → 내려받은 addon.py를 고르고 → 켭니다.
그런 다음 Blender 사이드바(3D 뷰포트에서 N)의 MCP for Blender 탭을 열고 Start MCP Server를 누르세요. 아래 연결 시작하기를 보세요.
업그레이드(기존 사용자)
처음 쓰는 분은 바로 빠른 시작으로 가세요. 기존 사용자는 아래를 보세요.
1. 실행합니다.
uvx mcp-for-blender@latest update
이 명령은 MCP 서버(uv의 캐시된 사본을 새로 고치거나 uv tool install을 업그레이드)와 설치된 모든 Blender 애드온 사본을 갱신하며, 바꾼 파일마다 .bak를 남깁니다. 릴리스보다 새로운 애드온은 낮추지 않고, 직접 고친 사본은 건드리지 않습니다. 먼저 무엇이 바뀔지 보려면 --dry-run을 붙이세요.
처음에는
@latest를 쓰세요. 2.1.7보다 오래된 릴리스에는update명령이 없고, uvx가 그런 판을 아직 캐시해 두었을 수 있습니다.
2. MCP 클라이언트(Claude Desktop, Cursor 등)를 다시 시작해서 새 서버를 시작하게 하세요.
3. Blender에서: 다시 시작하거나, Preferences → Add-ons에서 Interface: MCP for Blender를 껐다 켠 다음 Start MCP Server를 다시 누르세요.
클라이언트가 아직 옛 blender-mcp 패키지 이름으로 설정되어 있으면 update가 알려 주며, uvx mcp-for-blender setup으로 새 이름으로 바꿀 수 있습니다.
💡 참고 MCP 서버는 스스로 Blender 애드온 파일을 고치지 않습니다. 시작할 때 설치된 애드온이 번들된 사본보다 뒤처졌는지 확인해 업데이트 방법을 기록할 뿐이며, 실제로 쓰는 것은
update와install-addon입니다. 궤적(trajectory) 수집은 옛 애드온이 로드되어 있어도execute_code대체 경로로 동작합니다.
사용법
연결 시작하기

- Blender에서 3D 뷰 사이드바로 갑니다(보이지 않으면 N을 누릅니다)
- MCP for Blender 탭을 찾습니다
- 쓰고 싶은 체크박스를 켭니다(아래 기능 목록에서 더 자세히 봅니다)
- Connect to Claude를 누릅니다
- 터미널에서 MCP 서버가 실행 중인지 확인합니다
Claude와 함께 쓰기
Claude에 설정 파일을 적용하고 Blender에서 애드온이 실행 중이면, MCP for Blender 도구가 든 망치 아이콘이 보입니다.
![]()
기능 목록
AI는 모델링, 배치, 재질, 애니메이션, 리깅, 리토폴로지를 위한 Blender 파이썬을 스스로 씁니다. MCP는 파이썬만으로는 할 수 없는 일을 아홉 가지 도구로 더합니다.
| 도구 | 용도 |
|---|---|
execute_blender_code | 켜져 있는 Blender에서 파이썬 실행 |
look | viewport, camera, angles(자동으로 프레임을 잡은 여러 방향 시트, 어느 방향이든), frames(애니메이션 스트립)에서 결과를 solid, material, rendered, wireframe, xray로 그려 보거나, 렌더나 이미지 파일을 보여 줍니다 |
get_scene_info | 객체마다 한 줄로 요약한 장면 정보(배치, 재질, 토폴로지, 웨이트 등 고른 필드), root나 query로 더 들어갑니다 |
generate_3d | 한 번의 호출로 Tripo, Hunyuan3D, Hyper3D Rodin, Meshy로 모델을 생성해 가져옵니다. 프리미엄 생성기가 자동으로 우선됩니다 |
generate_gaussian_world | World Labs로 탐험할 수 있는 환경 전체를 생성해 가우시안 스플랫으로 가져옵니다(Blender 5.3 이상) |
search_assets / import_asset | Poly Haven HDRI · 텍스처 · 모델, Sketchfab 모델, Poly Pizza 로우폴리 모델 |
get_addon_status | Blender 버전, 애드온 버전, 어떤 라이브러리와 생성기가 켜져 있는지 |
disable_telemetry, record_trajectory_feedback | 데이터 수집 제어 |
Tencent Cloud의 Hunyuan3D(공식 API 모드)
애드온이 호출해야 하는 Tencent Cloud 서비스는 계정이 어디에 있는지에 따라 달라집니다.
| 계정 | 애드온이 호출하는 서비스 | 리전 | 사이드바 토글 |
|---|---|---|---|
| 중국 본토(cloud.tencent.com) | AI3D 3.0(ai3d, 버전 2025-05-13) | ap-guangzhou | International (Pro) account를 끈 채로 둡니다(기본값) |
| 국제(tencentcloud.com), Hunyuan-to-3D (Professional) | hunyuan, 버전 2023-09-01, PBR 켬 | ap-singapore | International (Pro) account를 켭니다 |
국제 자격 증명을 본토 엔드포인트로 보내면 AuthFailure.SignatureFailure나 ResourceUnavailable로 실패하므로, SecretId/SecretKey가 tencentcloud.com에서 온 것이라면 토글을 켜세요. 토글은 사이드바의 Tencent Hunyuan 3D → Official API 아래에 있습니다.
Tripo
Tripo는 텍스트 프롬프트나 참조 이미지로 텍스처가 입혀진 3D 모델을 생성합니다. 프리미엄으로는 키 없이, 또는 내 Tripo API 키로 쓸 수 있습니다. 프리미엄에서는 텍스트가 기본 품질을 쓰고, 이미지는 고품질 생성 한 번으로 셉니다. Tripo API 키 받기. 사이드바의 AI Model Generation 아래에서 Tripo를 켜고 Model을 고른 뒤 키를 붙여 넣으세요. tripo3d.com(중국) 계정이라면 애드온 환경 설정에서 Tripo Domain을 .com으로 두세요.
Meshy
Meshy는 텍스트 프롬프트나 참조 이미지로 텍스처가 입혀진 3D 모델을 생성하며, 실제 세계의 높이에 맞춰 크기를 잡고 원점을 바닥에 두므로 모델이 그럴듯한 크기로 땅 위에 서서 들어옵니다. 프리미엄으로는 키 없이, 또는 내 Meshy API 키로 쓸 수 있습니다. 프리미엄에서는 Meshy가 최신 모델을 쓰고 모델 하나가 표준 생성 한 번으로 셉니다. 내 API 키는 유료 Meshy 요금제가 필요합니다. Meshy API 키 받기. 사이드바의 AI Model Generation 아래에서 Meshy를 켜고 Model을 고른 뒤 키를 붙여 넣으세요. 내 키로 쓸 때 캐릭터를 "A-pose로" 또는 "T-pose로" 달라고 하면 Meshy가 그 자세로 생성해 바로 리깅할 수 있습니다.
World Labs
World Labs Marble은 텍스트 프롬프트, 이미지, 360° 파노라마로 탐험할 수 있는 월드 전체를 생성합니다. 가우시안 스플랫으로 들어오며, 객체 배치를 위한 숨겨진 충돌 메시와 월드 배경으로서의 파노라마가 함께 오고, 단위는 미터에 지면은 z=0입니다. 스플랫을 가져오고 렌더하는 Blender 5.3 이상이 필요하며, 더 낮은 버전에서는 이 옵션이 회색으로 비활성화됩니다. 프리미엄으로는 키 없이, 또는 내 World Labs API 키로 쓸 수 있습니다. 프리미엄에서는 모든 월드가 Marble 1.1이며 고품질 생성 한 번을 씁니다(Pro 이상). 내 키로 쓸 때는 사이드바의 모델을 씁니다. Marble 1.1 Plus(기본값, 더 큰 월드) 또는 Marble 1.1입니다. World Labs API 키 받기. API 크레딧은 Marble 앱 크레딧과 별개입니다. 사이드바의 Gaussian Worlds 아래에서 World Labs를 켜고 Model을 고른 뒤 키를 붙여 넣으세요. 내 키로 쓸 때, 한 장소를 이름 순서대로 돌며 찍은 사진 최대 4장이 든 폴더로 월드 하나를 만들 수 있습니다.
Poly Haven
Poly Haven은 HDRI, 텍스처, 모델 약 2,400개를 공개하며, 모두 CC0이고 무료이며 에셋을 팔지 않고 기부로 운영됩니다. API 키도 계정도 필요 없고, 걱정할 만한 요청 제한도 없습니다.
3D 뷰 사이드바에서 Poly Haven을 켜세요. 설정은 그게 전부입니다.
사용 예:
"흐린 오후 HDRI로 장면을 밝히고 벽에 녹슨 금속 텍스처를 입혀 줘"
Claude는 search_assets(source="polyhaven", query="overcast afternoon", asset_type="hdris")를 호출하는데, 이는 키워드를 맞추는 대신 의도를 이해합니다. "couch"가 소파를 찾고, 어떤 언어로도 작동합니다. previews=3은 대역폭을 쓰기 전에 상위 결과의 썸네일을 붙여 줍니다. import_asset(source="polyhaven", id="...", asset_type="textures", apply_to=["Wall"])은 텍스처를 내려받아 한 번의 호출로 적용합니다.
검색은 카테고리 경로나 속성(HDRI는 날씨와 시간대, 텍스처는 표면 용도와 상태 등)으로도 거를 수 있으며, 알 수 없는 속성은 올바른 속성 목록과 함께 오류를 냅니다.
모델은 작가가 만든 파일인 .blend에서 가져옵니다. glTF, FBX, USD 판은 그것에서 만들어지며 재질 세부가 줄어듭니다. 텍스처는 재질을 움직이는 맵으로 Principled 재질을 만들고, 아무도 읽지 않는 재포장과 대체 규약은 건너뜁니다. HDRI는 파일에 포장되므로 조명이 저장되고 다른 곳에서 다시 열려도 유지되며, 내가 만든 월드를 덮어쓰지 않고 새 월드로 들어옵니다.
라이선스와 출처 표기: 모든 Poly Haven 에셋은 CC0입니다. 상업이든 아니든 어떤 용도로든 누구에게도 출처를 밝힐 필요가 없습니다. 다만 API 약관은 라이브 API 위에 만든 소프트웨어가 에셋의 출처를 분명히 하라고 요구하므로, 검색과 가져오기 응답이 출처를 밝히고 에셋 페이지를 링크합니다. 가져올 때 polyhaven_id, polyhaven_url, polyhaven_authors, polyhaven_resolution, polyhaven_licence가 가져온 객체 · 재질 · 이미지 · 월드에 커스텀 속성으로 기록되어, 나중에 .blend를 여는 사람도 에셋과 그것을 만든 작가를 찾을 수 있습니다.
Poly Pizza
Poly Pizza는 구조된 Google Poly 보관소를 포함해 약 10,600개의 무료 로우폴리 모델을 호스팅합니다. 양식화된 게임 에셋을 구하기에 가장 좋은 곳입니다. 모든 모델이 자체로 완결된 .glb 하나이고, 지오메트리가 Sketchfab보다 훨씬 가볍습니다.
- poly.pizza/settings/api에서 무료 API 키를 받습니다
- 3D 뷰 사이드바에서 Use assets from Poly Pizza를 켭니다
- 나타나는 API Key 칸에 키를 붙여 넣습니다(또는 Edit → Preferences → Add-ons → MCP for Blender 아래에 영구히 저장합니다)
사용 예:
"Poly Pizza에서 CC0 라이선스의 로우폴리 의자를 찾아 1미터 높이로 가져와 줘"
Claude는 search_assets(source="polypizza", query="chair", licence="CC0")를 호출해 일치하는 것마다 라이선스와 삼각형 수를 돌려받고, 그다음 import_asset(source="polypizza", id="...", target_size=1.0)를 호출합니다.
카테고리("Animals", "Furniture & Decor", "Transport", "Nature", "Buildings", "People & Characters", "Food & Drink", "Weapons", "Clutter", "Objects", "Scenes & Levels", "Other")로 거르거나 애니메이션이 있는 모델만 요청할 수도 있습니다.
출처 표기: Poly Pizza 목록의 약 69%는 CC-BY이며, 모델이 쓰이는 어느 곳에서든 제작자를 밝혀야 합니다. 가져올 때, 바로 쓸 수 있는 형식의 출처 표기 문구가 가져온 루트 객체마다 커스텀 속성 polypizza_attribution으로 기록되고(polypizza_id, polypizza_licence와 함께) .blend에 저장되어 세션이 끝나도 남습니다. 출처 표기가 필요 없는 모델을 쓰고 싶다면 licence="CC0"로 거르세요.
명령 예시
Claude에게 시킬 수 있는 일의 예입니다.
| 프롬프트 | 데모 |
|---|---|
| "던전을 배경으로 한 로우폴리 장면을 만들어 줘. 용이 금이 든 항아리를 지키고 있어" | 보기 |
| "Poly Haven의 HDRI, 텍스처, 바위와 식물 같은 모델로 해변 분위기를 만들어 줘" | 보기 |
| 참조 이미지를 주고 그것으로 Blender 장면을 만들게 하기 | 보기 |
| "지금 장면의 정보를 가져와서 그걸로 threejs 스케치를 만들어 줘" | 보기 |
| "Hyper3D로 정원 요정(gnome) 3D 모델을 생성해 줘" | |
| "Meshy로 나무 흔들의자를 생성해 줘" | |
| "Tripo로 도자기 찻주전자를 생성해 줘" | |
| "햇살이 드는 지중해풍 안뜰을 월드로 생성한 다음 거기에 분수를 놓아 줘" | |
| "이 방을 Poly Pizza의 로우폴리 가구로 채워 줘" | |
| "이 자동차를 빨간색 금속으로 만들어 줘" | |
| "구를 만들어서 큐브 위에 놓아 줘" | |
| "조명을 스튜디오처럼 만들어 줘" | |
| "카메라가 장면을 향하게 하고 아이소메트릭으로 만들어 줘" |
영구 API 자격 증명
MCP for Blender는 Blender 애드온 환경 설정으로 영구 자격 증명을 지원합니다.
Edit → Preferences → Add-ons → MCP for Blender
Blender를 다시 시작해도 남도록 다음 값들을 거기에 저장할 수 있습니다.
- Sketchfab API 키
- Poly Pizza API 키
- Hyper3D API 키
- Hunyuan3D SecretId / SecretKey
- Hunyuan3D API URL
- Meshy API 키
- Tripo API 키
- World Labs API 키
헤드리스 환경이나 CI에서는 환경 변수로 자격 증명을 넣을 수도 있습니다.
| 변수 |
|---|
BLENDERMCP_SKETCHFAB_API_KEY |
BLENDERMCP_POLYPIZZA_API_KEY |
BLENDERMCP_HYPER3D_API_KEY |
BLENDERMCP_HUNYUAN3D_SECRET_ID |
BLENDERMCP_HUNYUAN3D_SECRET_KEY |
BLENDERMCP_HUNYUAN3D_API_URL |
BLENDERMCP_MESHY_API_KEY |
BLENDERMCP_TRIPO_API_KEY |
BLENDERMCP_WORLDLABS_API_KEY |
내 키로 쓰는 Hyper3D는 메인 사이트 경로와 fal.ai 경로 모두에서 Gen-2.5-Medium 등급을 씁니다. 무료 체험 키는 메인 사이트 모드에서만 쓸 수 있으며, fal.ai는 내 fal.ai API 키가 필요합니다. 체험 키 버튼은 fal.ai 모드에서는 숨겨집니다.
문제 해결
| 문제 | 해결 |
|---|---|
| 연결 문제 | Blender 애드온 서버가 실행 중이고 Claude에 MCP 서버가 설정되어 있는지 확인하세요. 터미널에서 uvx 명령을 실행하지 마세요. 처음 명령이 통과하지 않다가 그 뒤부터 잘 되기도 합니다. |
| 시간 초과 오류 | 요청을 단순하게 하거나 작은 단계로 나눠 보세요. |
| Poly Haven 다운로드 중 Blender가 멈춤 | 에셋은 Blender의 메인 스레드에서 내려받으므로 전송이 끝날 때까지 UI가 응답하지 않습니다. 해상도 단계마다 파일 크기가 대략 네 배로 커지니, 에셋을 카메라 가까이에 둘 것이 아니라면 1k나 2k를 요청하세요. |
| Poly Pizza 다운로드가 Cloudflare 챌린지로 실패 | static.poly.pizza는 봇 방어 뒤에 있어 데이터센터, VPN, 클라우드 IP를 막습니다. API 키는 문제없습니다. CDN은 키를 아예 보지 못합니다. 일반 연결에서 다시 시도하거나, .glb를 직접 내려받아 File → Import → glTF 2.0을 쓰세요. |
| 껐다 켜 보셨나요? | 여전히 연결 오류가 나면 Claude와 Blender 서버를 모두 다시 시작해 보세요. |
기술 세부 사항
통신 프로토콜
시스템은 TCP 소켓 위의 단순한 JSON 기반 프로토콜을 씁니다.
- 명령은
type과 선택 사항인params가 든 JSON 객체로 보냅니다 - 응답은
status와result또는message가 든 JSON 객체입니다
다른 기기에서 연결하기
애드온은 기본으로 localhost에서 듣습니다. 신뢰할 수 있는 다른 PC, Docker, WSL에서 연결을 받으려면 Edit > Preferences > Add-ons > MCP for Blender를 열어 Bind Address를 Blender 기기의 LAN IPv4 주소(또는 모든 인터페이스에 0.0.0.0)로 두고 Allow Remote Connections를 켠 다음 연결을 끊었다가 다시 연결하세요. 클라이언트 쪽에서는 BLENDER_HOST를 그 주소로, BLENDER_PORT를 Blender에 표시된 포트로 두세요.
원격 접속에는 인증도 암호화도 없고 클라이언트가 Blender에서 파이썬을 실행할 수 있습니다. 방화벽 뒤의 신뢰할 수 있는 네트워크에서만 쓰고, 공용 인터넷에서는 절대 쓰지 마세요. 기본 localhost 수신 지점으로 향하는 SSH 터널이 더 안전한 대안입니다.
한계와 보안 고려 사항
⚠️ 경고
execute_blender_code도구는 Blender에서 임의의 파이썬 코드를 실행하게 하므로 강력하지만 위험할 수 있습니다. 운영 환경에서는 주의해서 쓰세요. 쓰기 전에 항상 작업을 저장하세요.
- Poly Haven은 모델, 텍스처, HDRI 이미지를 내려받아야 합니다. 쓰고 싶지 않다면 Blender의 체크박스에서 끄세요.
- 복잡한 작업은 더 작은 단계로 나눠야 할 수 있습니다.
원격 측정 제어
원격 측정은 옵트인입니다. 내 콘텐츠의 수집은 기본으로 꺼져 있으며 명시적으로 켜기 전까지 꺼져 있습니다.
기본으로 수집되는 것(옵트인 없이): 활성 사용자 수와 어떤 도구가 쓰이는지 세기 위한 최소한의 익명 사용 기록입니다. 무작위로 만든 설치 ID, 세션 ID, 도구 이름, 성공 여부, 걸린 시간, MCP for Blender와 Blender 버전, 운영 체제, 타임스탬프입니다.
옵트인하지 않으면 절대 수집되지 않는 것: 프롬프트, 생성된 코드, 뷰포트 스크린샷, 장면 데이터, 궤적 단계입니다.
옵트인하려면 — Edit → Preferences → Add-ons → MCP for Blender로 가서 원격 측정 동의 체크박스를 켜세요. 일부 MCP 클라이언트는 대화를 시작할 때 일회성 옵트인 안내도 보여 줍니다. 옵트인하면 프롬프트, 생성된 코드, 스크린샷, 궤적 데이터가 수집 대상에 더해집니다. 자세한 내용은 이용 약관을 보세요. 같은 곳에서 언제든 다시 끌 수 있습니다.
원격 측정을 완전히 끄려면(최소한의 익명 사용 기록 포함) 환경 변수를 설정하세요.
DISABLE_TELEMETRY=true uvx mcp-for-blender
또는 MCP 설정에 추가하세요.
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": ["mcp-for-blender"],
"env": {
"DISABLE_TELEMETRY": "true"
}
}
}
}
원격 측정 데이터는 내 이름이나 계정과 연결되지 않습니다. MCP for Blender를 개선하고, 연구하고, AI 모델을 학습시키는 데 쓰일 수 있습니다.
무엇이 수집되는지, 옵트인할 때 내가 부여하는 라이선스에 대한 자세한 내용은 TERMS_AND_CONDITIONS.md에 있습니다.
피드백
MCP for Blender에 대한 피드백을 적극적으로 찾고 있습니다. 의견이 있다면 여기에 남겨 주세요.
더 자세한 피드백이 있다면 여기에서 통화를 예약할 수 있습니다. 프로젝트에서 이름을 밝혀 드립니다.
커뮤니티 참여하기
피드백을 주고, 영감을 얻고, MCP 위에 만들어 보세요: Discord
기여하기
기여를 환영합니다! 부담 없이 풀 리퀘스트를 보내 주세요.
면책 조항
이 프로젝트는 서드파티 연동이며 Blender가 만든 것이 아닙니다. 제작: Siddharth.
별 기록
MCP for Blender가 도움이 된다면 저장소에 별을 눌러 주세요