blender-fx-mcp

자연어 명령 · 물리 효과 · 장면 미리보기

말로 시키면 블렌더에서 건물을 부수고, 터뜨리고, 물을 쏴 주는 MCP 서버. / Tell an AI "collapse it from the left" and Blender does it.

처음 한 번 (4단계) — 단계마다 blender-fx-doctor 의 그 줄이 [OK] 면 된 것입니다(순서도 doctor 의 "다음 할 일"과 같습니다).

1. uv 설치 — macOS brew install uv, Linux curl -LsSf https://astral.sh/uv/install.sh | sh, Windows 는 해결법의 한 줄 → [OK] uv

2. 블렌더 5.2 + 수신기 애드온 — blender-mcp 의 addon.py 를 받아 블렌더 Edit → Preferences → Add-ons → 오른쪽 위 ▾ → Install from Disk 로 설치하고 체크 → [OK] 수신기 애드온 파일(blender-mcp) · 막히면 해결법

3. 블렌더에서 Connect — 3D 화면에서 N 키 → BlenderMCP 탭 → Connect to MCP server → [OK] 수신기 연결 · 막히면 해결법

4. 클로드에 등록(다른 클라이언트는 examples/) → [OK] MCP 클라이언트 등록 · 막히면 해결법:

claude mcp add -s user blender-fx -- uvx blender-fx-mcp
uvx --from blender-fx-mcp blender-fx-doctor   # 점검: 끝에 "모두 정상입니다."

첫 명령 예시 — AI에게 이렇게 말합니다:

연습용 건물 하나 만들고, 왼쪽에서 충격 줘서 콘크리트처럼 무너뜨려. 끝나면 미리보기 보여 줘.

미리보기가 검거나 효과가 안 보이면 해결법, 오류 문장이 나오면 문제 해결에서 그 문장을 찾습니다.

붙여 넣기 대신 클라이언트의 / 메뉴에서 /first_demo(같은 순서: 연결 확인 → 건물 → 스냅샷 → 붕괴 → 미리보기, impact·material 을 고를 수 있음)를, 되돌릴 때는 /undo_last(스냅샷 목록 → 확인 → restore)를 골라도 됩니다(Claude Code 에서는 /blender-fx:first_demo 처럼 보일 수 있음).

더 많은 예시(유리 슬로모션·모델 가져와 부수기·폭발·물 쏘기)와 실제 결과 수치는 docs/recipes.md.

[English] An MCP server that lets an AI (Claude, Codex, Cursor, any MCP client) build Blender FX from plain language: building destruction, explosions with smoke and fire, water splashes, fire, particles, wind, ocean and cloth. You direct ("collapse it from the left, slower, more dust"), the AI picks a tool, Blender simulates, and preview frames come back. No Blender knowledge needed. Requires Blender 5.2, the blender-mcp receiver add-on inside Blender, and uv. Set BLENDER_FX_LANG=en for English messages. Full English guide: English (install, first command, all tools).

AI에게 말로 시키면 블렌더에서 아무 3D 모델이나 물리에 맞게 부수고, 물을 원하는 방향·점성으로 쏘고, 폭발·불·연기·비·눈·바다·깃발까지 만들어 주는 MCP 서버입니다. 블렌더를 몰라도 됩니다. 사용자는 감독처럼 "왼쪽에서 충격 줘서 무너뜨려, 더 잘게, 느리게"라고 말하고, AI가 도구를 골라 실행한 뒤 미리보기 프레임을 보여 줍니다.

어떻게 돌아가나

[클로드 / 코덱스 / 커서 등 MCP 클라이언트]
        │  "Building을 왼쪽에서 부숴"
        ▼
[blender-fx-mcp]  ← 이 프로젝트. 검증된 레시피를 도구로 감쌌다
        │  파이썬 레시피 전송 (localhost:9876)
        ▼
[블렌더 안 수신기 애드온 (blender-mcp)]
        │
        ▼
[리지드바디 · Mantaflow 연기/물 → 굽기 → 렌더] → 프레임 이미지가 AI에게 돌아온다

AI는 코드를 짜지 않습니다. 도구와 값만 고릅니다. 그래서 블렌더 버전이 바뀌어도 레시피 한 곳만 고치면 됩니다. 파일별 역할과 시험 경로는 docs/architecture.md.

Related MCP server: Blender MCP

준비물 3가지

순서는 첫 화면의 4단계·doctor 의 "다음 할 일"과 같습니다.

1. uv (파이썬 실행기): macOS brew install uv. Windows·Linux 는 docs.astral.sh/uv 또는 doctor 가 알려 주는 명령

2. 블렌더 5.2 (5.x LTS 기준으로 만들었습니다) 와 블렌더 안 수신기 애드온: blender-mcp의 addon.py를 Edit → Preferences → Add-ons → 오른쪽 위 ▾ → Install from Disk 로 설치하고 켭니다.

3. 수신기 켜기: 3D 화면에서 N 키 → BlenderMCP 탭 → Connect to MCP server 를 누르면 수신기가 켜집니다(블렌더를 켤 때마다).

준비물이 갖춰졌는지 한 번에 확인:

uvx --from blender-fx-mcp blender-fx-doctor

오류 문장별 해결법(연결 거부·시간 초과·포트 충돌·유체 굽기 실패·검은 미리보기): docs/troubleshooting.md

질문·버그·보안 신고를 어디로 보내는지, 응답 목표, 지원하는 블렌더·파이썬 판: SUPPORT.md

도움 받기 — ① uvx --from blender-fx-mcp blender-fx-doctor --issue 를 돌려 결과를 복사(집 폴더는 ~ 로 가려짐) ② 버그 신고 · 질문 · 기능 요청 중 맞는 양식에 붙여 넣기 ③ 첫 답 목표: 버그 7일, 질문·기능 14일 안. 보안 문제는 공개 이슈 대신 SECURITY.md 로.

이슈 분류·의존성 갱신·출시·지원 판 정리 규칙: docs/maintenance.md

설치 (한 줄)

클로드 코드:

claude mcp add -s user blender-fx -- uvx blender-fx-mcp

로컬 폴더에서 개발 중이면:

claude mcp add -s user blender-fx -- uv --directory /절대/경로/blender-fx-mcp run blender-fx-mcp

클로드 데스크톱 앱은 ~/Library/Application Support/Claude/claude_desktop_config.json의 mcpServers에, 코덱스는 ~/.codex/config.toml의 [mcp_servers.blender_fx]에 같은 명령을 적습니다. 바로 붙여 넣을 수 있는 설정(클로드 데스크톱·커서·코덱스)은 examples/에 있습니다. 등록 후 앱을 완전히 껐다 켜야 도구가 보입니다. 안 보이면 해결법.

AI 없이 블렌더 쪽만 먼저 확인(첫 렌더까지): 블렌더를 켜고 Connect 를 누른 뒤, 설치판에 blender-fx-first-render 진입점이 있으면 저장소 없이 실행합니다.

uvx --from blender-fx-mcp blender-fx-first-render   # [1/5] 연결 확인 → 스냅샷 → 건물 → 붕괴 → 미리보기, 끝에 PNG 경로·여는 명령

저장소에서 개발 중이거나 설치판에 진입점이 없으면, 저장소 루트에서 실행합니다.

uv run python examples/first_render.py

연결이 안 되면 다음 할 일을 출력하고 종료 코드 2 입니다. 자세한 설명은 examples/README.md.

매일 쓰는 순서

1. 블렌더를 켠다.

2. N 키 → BlenderMCP 탭 → 수신기 켜기.

3. AI에게 말한다: "연습용 건물 하나 만들고, 왼쪽에서 충격 줘서 콘크리트처럼 무너뜨려."

4. 돌아온 미리보기 프레임을 보고 다시 말한다: "더 잘게", "맞은 데만 부서지게", "유리처럼", "물을 왼쪽에서 옆으로 쏴", "꿀처럼 걸쭉하게", "중력 절반", "슬로모션", "불 붙여", "눈 내리게", "로우앵글로", "노을로".

5. 마음에 들면: "영상으로 뽑아 줘", "장면 저장해 줘", "glb로 내보내 줘."

자기 모델이 있으면: "~/Desktop/tower.glb 가져와서 12m 크기로 세우고 왼쪽에서 부숴." (/ 메뉴의 /my_model 은 가져온 뒤 inspect_mesh 로 상태부터 봅니다)

도구 목록

미리보기·영상·.blend 는 ~/blender-fx-output/ 아래 실행별 폴더에 저장됩니다. (BLENDER_FX_OUT으로 변경) 연기·물 캐시는 같은 폴더의 cache_fluid/, cache_liquid/에 쌓입니다. 용량이 커지면 지워도 됩니다.

개발·테스트

1. pytest 시험

개발 의존성을 준비한 뒤 서버 동작과 레시피를 시험합니다. 블렌더 실행 파일이 필요한 레시피 시험은 파일을 찾지 못하면 건너뜁니다.

uv sync --group dev
uv run pytest -q

2. headless 레시피 실행

블렌더 실행 파일이 필요합니다. 창 없이 띄워 레시피를 소켓 없이 검증합니다.

uv run blender-fx-headless demo-windows destroy render
uv run blender-fx-headless demo destroy-hold explode smoke
uv run blender-fx-headless demo water-side smoke
uv run blender-fx-headless demo snapshot destroy restore
uv run blender-fx-headless demo destroy video save

3. e2e_socket 연결 시험

블렌더와 BlenderMCP 수신기가 켜져 있어야 합니다. 실제 MCP 클라이언트 → 서버 → 소켓 → 블렌더 경로와 이미지 응답을 확인합니다:

uv run python scripts/e2e_socket.py

내려받은 무료 에셋 부수기

인터넷에서 받은 GLB/FBX 모델은 대개 "깨끗한 solid" 가 아닙니다. 바퀴가 몸통에 박혀 있거나, 내용물이 바닥에 딱 붙어 있거나, 껍데기뿐이거나, 꼭짓점이 쪼개져 있습니다. import_model 이 가져올 때 꼭짓점을 다시 붙이고, destroy 가 조각내기 전에 겹친 덩어리를 하나로 정리합니다. 아래는 그런 결함을 그대로 재현해 만든 시험용 GLB 7개로 잰 값입니다 (내려받은 실제 파일이 아니라, 결함을 일부러 심어 만든 모델입니다).

부피 보존(volume_kept) 은 조각 부피의 합 ÷ 원본 부피입니다. 1.00 이면 물질이 사라지지도 불어나지도 않았다는 뜻이고, 그래야 무게와 낙하가 물리에 맞습니다. 조각 500개까지 1.00 을 지킵니다.

게임 캐릭터처럼 부품이 여러 개인 파일

한 파일에 부품이 여러 개 들어 있으면 import_model 이 목록을 알려 줍니다. 보이지 않는 충돌용 껍데기가 섞여 있으면 경고도 합니다. 원하는 것만 고르려면 이렇게 하세요.

import_model(path="adventurer.glb", size=2.0, parts=["Adventurer", "Backpack"])

부품 이름은 일부만 적어도 됩니다. 면이 하나도 없는 부품(리깅 조작용 위젯 등)은 자동으로 빠집니다. .blend 파일 하나에 그런 위젯이 132개 들어 있던 적도 있습니다. 실제 CC0 게임 캐릭터(면 10,198개, 부품 5개 + 껍데기 구 1개)로 재면 조각 47/50, 부피 보존 1.00 입니다. 부품끼리 서로 관통하는 모델은 자동으로 느리지만 정확한 계산으로 넘어갑니다(50조각에 약 100초).

부수기 전에 inspect_mesh 로 한 번 보세요. 닫히지 않은 껍데기는 shell_thickness 로 두께를 주면 단면이 비어 보이지 않습니다.

지금 한계 (정직하게)

• 조각내기는 보로노이 + 불리언이라 정확하지만, 조각 수가 많으면 느립니다. 얇은 벽 모델 기준 120개 2초, 300개 7초, 500개 15초입니다.

• 면이 20,000개를 넘는 모델은 조각내기 전에 그 수까지 자동으로 줄입니다(decimate_to, 0 이면 끄기). 아주 가는 장식은 이때 뭉개질 수 있습니다.

• 뼈대 애니메이션이 들어 있는 모델은 현재 자세 그대로 굳혀서 부숩니다. 애니메이션은 따라가지 않습니다.

• 부품끼리 서로 관통하는 모델은 정확하지만 느린 계산으로 넘어갑니다. 50조각에 약 100초입니다.

• glue(조각 접착)는 조각마다 이웃 4개까지, 모두 600개까지 제약을 만들어 굽기가 느려집니다. 느리면 pieces 를 줄이거나 glue="none" 으로 다시 시키세요.

• restore 는 블렌더가 그 .blend 파일을 엽니다. 직전 상태는 before_restore 로 자동 저장되지만, 여러 단계 실행 취소는 아닙니다.

• sky="procedural" 과 연기·물은 EEVEE·Cycles 에서만 보입니다. 빠른 미리보기에서는 도구가 그 사실을 알려 줍니다.

• HDRI 는 가지고 있는 파일만 씁니다. 인터넷에서 받아오지 않습니다.

• 물은 계산 격자보다 작은 물 덩어리는 사라집니다. 그럴 때 도구가 필요한 resolution 숫자를 알려 줍니다.

• 물 해상도 64 에서 표면에 각이 보입니다. 128 이상이 곱지만 굽기가 몇 배 느립니다.

• 구간 슬로모션은 물리·연기·물에만 걸립니다. 파티클까지 느리게 하려면 set_timing(global_slow=) 을 쓰세요(전체 길이가 늘어납니다).

• export_model 의 .abc 는 물 표면과 조각 움직임을 담지만, 연기(볼륨)는 어떤 형식으로도 나가지 않습니다.

• 창문은 벽을 실제로 파낸 것이지만 실내는 없습니다.

• 블렌더 5.2에서만 확인했습니다.

• 메시지 언어는 BLENDER_FX_LANG(ko/en)로 정합니다. 없으면 로캘(LANG 등)이 한국어면 한국어, 다른 언어면 영어이고, 로캘이 없으면(창 앱이 띄운 서버에서 흔함) 한국어입니다.

• 수신기 애드온은 blender-mcp 것을 빌려 씁니다. 그쪽 포트·명령이 바뀌면 같이 고쳐야 합니다.

• blender-mcp 서버와 이 서버를 같이 켜 두면 수신기가 하나라 끊길 수 있습니다. 문제가 나면 하나만 켜세요.

로드맵

• v0.1 파괴 (완료)

• v0.2 폭발: Mantaflow 연기·불 + 힘장 + 파편 (완료)

• v0.3 물: Mantaflow 액체 스플래시, mp4 렌더, .blend 저장, doctor (완료)

• v0.4 FX 작업 도구: 모델 가져오기/내보내기, 카메라·흔들림, 조명 프리셋, 슬로모션, 불·연기, 파티클, 바람, 바다, 깃발, 캐시 정리 (완료)

• v0.5 스냅샷/되돌리기, 조각 접착(구조 붕괴), 창문 건물, 연기·조각 충돌, 하늘 텍스처·HDRI, 바닥 재질, 영어 메시지 (완료)

• v0.6 보로노이 파괴(아무 메시나, 부피 보존), 메시 자동 수리·진단, 물 방향·점성·모드, 전 설정 개방(set_physics/set_render), 전체 슬로모션, Alembic 내보내기 (완료)

• v0.6.1 내려받은 에셋 대응: 꼭짓점 재결합, 겹친 덩어리 정리, 씨앗 배치 교정 (완료)

• v0.6.3 충격체 실제 표면 조준, .blend 위젯 자동 제외, 소켓 경로 재확인 (완료)

• v0.6.2 실제 게임 캐릭터 대응: 부품 선택, 스킨 메시 굽기, 비다양체 수리, 볼록도·무게 표시 교정 (완료)

• v1.0 프리셋 JSON 분리, 자체 수신기 애드온 동봉, 도로·차량 같은 소품 프리셋, 도구 설명 영어화

기여

CONTRIBUTING.md를 보세요. 레시피 하나 = 파일 하나라, 새 효과는 recipes/ 에 파일을 추가하고 server.py 에 도구 하나를 붙이면 됩니다. 참여할 때는 행동 강령을 지켜 주세요.

보안

수신기는 인증 없이 localhost:9876 으로 받은 파이썬을 블렌더 안에서 실행합니다. 포트를 밖으로 열지 마세요. 위험과 비공개 신고 방법은 SECURITY.md.

라이선스

MIT (이 저장소). 블렌더 안 수신기 애드온은 blender-mcp 프로젝트 것이며 그쪽 라이선스를 따릅니다. 함께 설치되는 파이썬 패키지의 라이선스는 docs/third-party-licenses.md(모두 허용적 라이선스, CI 가 확인).

English

What you need

Four steps, once. Each step is done when its blender-fx-doctor line shows [OK] (same order as doctor's "Next steps").

1. Install uv (Python runner) — macOS brew install uv, Linux curl -LsSf https://astral.sh/uv/install.sh | sh, Windows: the one line in troubleshooting → [OK] uv

2. Blender 5.2 + the receiver add-on — download addon.py from blender-mcp, then in Blender Edit → Preferences → Add-ons → top-right ▾ → Install from Disk, and tick it → [OK] receiver add-on file (blender-mcp) · stuck: fix

3. Connect in Blender — in the 3D view press N → BlenderMCP tab → Connect to MCP server. It listens on localhost:9876 → [OK] receiver connection · stuck: fix

4. Register with your AI client — see Install below → [OK] MCP client registration · stuck: fix

Check everything at once (Python, mcp, uv, Blender, receiver, client registration, output folder):

uvx --from blender-fx-mcp blender-fx-doctor

Fixes for each error message (connection refused, timeout, port in use, fluid bake failed, black preview): docs/troubleshooting.md

Where to ask questions or report bugs, reply targets and supported Blender/Python versions: SUPPORT.md

Getting help: ① run uvx --from blender-fx-mcp blender-fx-doctor --issue and copy the output (your home folder is masked as ~) ② paste it into the matching form: bug report · question · feature request ③ first reply targets: 7 days for bugs, 14 days for questions and ideas. Security problems go to SECURITY.md, not a public issue.

How issues, dependency updates, releases and old versions are handled: docs/maintenance.md

Install

Claude Code:

claude mcp add -s user blender-fx -e BLENDER_FX_LANG=en -- uvx blender-fx-mcp

Claude Desktop, Codex, Cursor and other MCP clients: add the same command (uvx blender-fx-mcp) to the client's MCP server config with the environment variable BLENDER_FX_LANG=en, then fully restart the app. Ready-to-paste configs for Claude Desktop, Cursor and Codex are in examples/. If the tools do not show up, see troubleshooting.

Check the Blender side first, without an AI (up to a first render): open Blender and click Connect. If the installed package provides the blender-fx-first-render entry point, run it without a checkout:

BLENDER_FX_LANG=en uvx --from blender-fx-mcp blender-fx-first-render   # [1/5] connection → snapshot → building → collapse → preview, then PNG paths and an open command

When developing in a checkout, or if the installed package lacks that entry point, run from the repository root:

BLENDER_FX_LANG=en uv run python examples/first_render.py

Without a connection it prints the next step and exits with 2. Details: examples/README.md ("First render from the terminal").

First command

Open Blender, connect the receiver, then tell your AI:

Make a practice building, hit it from the left and collapse it like concrete. Show me a preview when it's done.

If the preview is black or the effect is missing, see the fix; for an error message, search troubleshooting for it.

Or pick /first_demo from your client's / menu instead of pasting (same steps: check connection → building → snapshot → collapse → preview; optional impact and material), and /undo_last to go back (snapshot list → confirm → restore). Claude Code may show them as /blender-fx:first_demo.

Then keep directing from the preview frames: "smaller pieces", "only break where it was hit", "like glass", "shoot water sideways from the left", "thick like honey", "half gravity", "slow motion", "set it on fire", "make it snow", "low angle", "sunset". When you like it: "render a video", "save the scene", "export as glb".

Your own model works too: "Import ~/Desktop/tower.glb, stand it up 12 m tall and break it from the left." (the /my_model prompt checks the mesh with inspect_mesh first) More examples with measured results: docs/recipes.md (English section).

Tools

Outputs go to per-run folders under ~/blender-fx-output/ (BLENDER_FX_OUT). Smoke and water caches pile up in cache_fluid/ and cache_liquid/ there; delete them when they get large.

Security, contributing, license

The receiver runs Python it receives on localhost:9876 without authentication. Never expose that port. See SECURITY.md for the risks and private reporting. Contributions: CONTRIBUTING.md and the Code of Conduct; how the code fits together: docs/architecture.md. License: MIT; licenses of the installed dependencies are listed in docs/third-party-licenses.md.