Metadata-Version: 2.5
Name: blender-fx-mcp
Version: 0.7.0
Summary: AI가 말로 시키면 블렌더 FX(파괴·폭발·물)를 만들어 주는 MCP 서버 / Blender FX (destruction, explosion, water) MCP server for AI clients
Project-URL: Homepage, https://github.com/choisam4u-creator/blender-fx-mcp
Project-URL: Documentation, https://github.com/choisam4u-creator/blender-fx-mcp#readme
Project-URL: Issues, https://github.com/choisam4u-creator/blender-fx-mcp/issues
Project-URL: Changelog, https://github.com/choisam4u-creator/blender-fx-mcp/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/choisam4u-creator/blender-fx-mcp/security/policy
Author: Sam Choi
License-Expression: MIT
License-File: LICENSE
Keywords: blender,destruction,explosion,fluid,mcp,model-context-protocol,simulation,vfx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=2.0
Description-Content-Type: text/markdown

# blender-fx-mcp

[![ci](https://github.com/choisam4u-creator/blender-fx-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/choisam4u-creator/blender-fx-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue.svg)](pyproject.toml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/choisam4u-creator/blender-fx-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/choisam4u-creator/blender-fx-mcp)

<!-- mcp-name: io.github.choisam4u-creator/blender-fx-mcp -->

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

<!-- 결과 GIF 자리: docs/demo-script.md 대본으로 촬영해 docs/media/demo.gif 를 넣은 뒤 아래 줄의 주석을 푼다.
![결과 GIF 자리 — docs/demo-script.md 대본으로 촬영 후 docs/media/demo.gif 로 교체](docs/media/demo.gif)
-->

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

<!-- setup-steps: uv, addon, connection, client -->
1. **uv 설치** — macOS `brew install uv` (Windows·Linux 명령은 doctor 가 알려 줍니다) → `[OK] uv`
2. **블렌더 5.2 + 수신기 애드온** — [blender-mcp](https://github.com/ahujasid/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/](examples/)) → `[OK] MCP 클라이언트 등록`:

```bash
claude mcp add -s user blender-fx -- uvx --from git+https://github.com/choisam4u-creator/blender-fx-mcp blender-fx-mcp
uvx --from git+https://github.com/choisam4u-creator/blender-fx-mcp blender-fx-doctor   # 점검: 끝에 "모두 정상입니다."
```

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

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

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

더 많은 예시(유리 슬로모션·모델 가져와 부수기·폭발·물 쏘기)와 실제 결과 수치는 [docs/recipes.md](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](https://github.com/ahujasid/blender-mcp) receiver add-on inside Blender, and `uv`. Set `BLENDER_FX_LANG=en` for English messages. **Full English guide: [English](#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](docs/architecture.md).

## 준비물 3가지

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

1. **uv** (파이썬 실행기): macOS `brew install uv`. Windows·Linux 는 [docs.astral.sh/uv](https://docs.astral.sh/uv/) 또는 doctor 가 알려 주는 명령
2. **블렌더 5.2** (5.x LTS 기준으로 만들었습니다) 와 **블렌더 안 수신기 애드온**: [blender-mcp](https://github.com/ahujasid/blender-mcp)의 `addon.py`를
   Edit → Preferences → Add-ons → 오른쪽 위 ▾ → Install from Disk 로 설치하고 켭니다.
3. **수신기 켜기**: 3D 화면에서 `N` 키 → **BlenderMCP** 탭 → **Connect to MCP server** 를 누르면 수신기가 켜집니다(블렌더를 켤 때마다).

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

```bash
uvx --from git+https://github.com/choisam4u-creator/blender-fx-mcp blender-fx-doctor
```

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

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

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

## 설치 (한 줄)

클로드 코드:

```bash
claude mcp add -s user blender-fx -- uvx --from git+https://github.com/choisam4u-creator/blender-fx-mcp blender-fx-mcp
```

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

```bash
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/](examples/)에 있습니다.
등록 후 앱을 완전히 껐다 켜야 도구가 보입니다. 안 보이면 [해결법](docs/troubleshooting.md#tools-not-visible-in-the-client).

**AI 없이 블렌더 쪽만 먼저 확인**(첫 렌더까지): 이 저장소를 받은 폴더에서 블렌더를 켜고 Connect 를 누른 뒤

```bash
uv run python examples/first_render.py   # [1/5] 연결 확인 → 스냅샷 → 건물 → 붕괴 → 미리보기, 끝에 PNG 경로
```

연결이 안 되면 다음 할 일을 출력하고 종료 코드 2 입니다. 자세한 설명은 [examples/README.md](examples/README.md#터미널에서-첫-렌더까지--first-render-from-the-terminal).

## 매일 쓰는 순서

1. 블렌더를 켠다.
2. `N` 키 → BlenderMCP 탭 → 수신기 켜기.
3. AI에게 말한다: **"연습용 건물 하나 만들고, 왼쪽에서 충격 줘서 콘크리트처럼 무너뜨려."**
4. 돌아온 미리보기 프레임을 보고 다시 말한다: "더 잘게", "맞은 데만 부서지게", "유리처럼", "물을 왼쪽에서 옆으로 쏴", "꿀처럼 걸쭉하게", "중력 절반", "슬로모션", "불 붙여", "눈 내리게", "로우앵글로", "노을로".
5. 마음에 들면: "영상으로 뽑아 줘", "장면 저장해 줘", "glb로 내보내 줘."

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

## 도구 목록

| 도구 | 하는 일 |
|---|---|
| `doctor` | 준비물 점검(파이썬·mcp·uv·블렌더·수신기·클라이언트 등록·출력 폴더). 안 될 때 먼저 부른다 |
| `ping_blender` | 수신기와 연결되는지, 블렌더 판이 시험한 판인지 확인 |
| `list_objects` | 장면의 메시 이름·크기 목록 (부술 대상 고르기) |
| `inspect_mesh` | 부수기 전 모델 진단: 닫혀 있나, 부피, 오목한 정도, 면 수, 수리하면 얼마나 나아지나 |
| `make_demo_building` | 연습용 건물 + 바닥 + 카메라 + 조명 생성. `style`(plain/windows 창문 건물), `ground`(바닥 재질) |
| `destroy` | **아무 메시나** 보로노이(돌 깨지듯 다각형) 조각으로 부수고 물리로 무너뜨림. 메시 자동 수리 포함. 인자: `impact`(left/right/front/back/top/none), `material`(concrete/brick/glass/wood/stone/metal/ice/plaster), `pieces`, `pattern`(impact/uniform/radial/slabs), `focus`, `glue`(none/weak/medium/strong), `collision`(auto/convex/mesh/box/sphere), `interior`(단면 재질), `repair`, `shell_thickness`, `density`/`friction`/`bounce`, `dust`, `impact_power`, `time_scale`, `frames`, `seed` |
| `explode` | 폭발. `target`을 주면 건물을 조각낸 뒤 안에서 터뜨려 연기·불과 함께 날림. 없으면 `at=[x,y,z]` 위치에 연기·불만. 인자: `power`, `fire`, `frames`, `burst_frame`, `resolution`, `smoke_collision`(연기가 조각에 부딪힘) |
| `water` | **방향·모양·점성을 정하는 물**. `mode`(drop 떨어뜨리기 / stream 호스처럼 쏘기 / pool 물 채우기 / object 내 메시가 물이 됨), `direction_deg`, `pitch_deg`, `speed`, `shape`(sphere/box/column), `liquid`(water/oil/honey/lava/mercury/slime), `viscosity`, `surface_tension`, `gravity_scale`, `obstacles`, `spray`, `resolution`, `smoothing` |
| `splash` | `water(mode="drop")` 의 간단 버전 |
| `fire` / `smoke` | 계속 타오르는 불 / 피어오르는 연기. `resolution=0` 이면 대상 크기에 맞춰 자동. `density`, `dissolve`, `vorticity`, `noise`, `smoke_collision` |
| `particles` | 비·눈·불꽃·재. `kind`(rain/snow/sparks/ash), `area`, `count`, `size`, `gravity`, `drag`, `lifetime`, `speed` |
| `wind` | 바람 힘장. 파티클·깃발·연기를 민다. `direction_deg`, `strength`, `turbulence` |
| `ocean` | 바다 표면(파도 움직임). `size`, `wave_scale`, `choppiness`, `wind_velocity` |
| `cloth_flag` | 깃대에 걸린 깃발(천)이 바람에 펄럭임 |
| `import_model` | glb/gltf/fbx/obj/stl/usd/blend 모델을 가져와 하나로 합치고 크기 맞춰 바닥에 세움 |
| `export_model` | glb/gltf/fbx/obj/**abc** 로 내보내기. `.abc`(Alembic)는 물 표면과 조각 움직임을 프레임마다 담아 다른 프로그램에서 그대로 재생됨. `bake_physics=True` 면 조각 물리를 키프레임으로 |
| `camera` | 구도 프리셋 wide/medium/closeup/low/high/top/front/side + `angle_deg`, `height`, `lens` |
| `camera_shake` | 충돌·폭발 순간 카메라 흔들림 (`frame`, `strength`, `duration`) |
| `set_look` | 조명·하늘 분위기 day/sunset/night/overcast/studio. `sky="procedural"` 진짜 하늘 텍스처, `hdri=파일경로` 내 HDRI 사진으로 조명 |
| `set_ground` | 바닥 재질 asphalt/concrete/grass/sand/dirt/snow, `size`(m) |
| `snapshot` / `list_snapshots` / `restore` | 장면을 저장해 두고 언제든 그때로 되돌린다. 위험한 작업 전에 쓴다 |
| `clear_snapshots` | 오래된 스냅샷부터 지우고 최근 `keep`개(기본 5)를 남긴다. `before_restore` 는 늘 남김 |
| `set_timing` | 프레임 범위·fps·슬로모션. 구간(`slow_from`/`slow_to`/`slow_factor`)은 물리·연기·물에만, `global_slow` 는 파티클까지 전부 |
| `set_physics` | 중력 세기·기울기, 계산 하위단계·반복(정확도), 물리 속도, fps |
| `set_render` | 샘플 수, 모션블러, 해상도, 노출, 필름 룩, 배경 빼기 |
| `render_preview` | 현재 장면 다시 렌더. `quality="preview"` 빠름(연기·물 안 보임), `"smoke"` 연기·물 보임, `"final"` 고화질 |
| `render_video` | 장면 전체를 mp4(H.264)로 렌더 |
| `save_blend` | 현재 장면을 .blend 로 저장 (블렌더에서 직접 열어 손볼 수 있음) |
| `clear_caches` | 구운 캐시와 캐시 폴더 비우기 |
| `reset_destroy` | 이 도구가 만든 것(조각·충격체·연기·물·파티클·바다·깃발)을 지우고 원본 되살리기 |

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

## 개발·테스트

블렌더를 창 없이 띄워 레시피를 소켓 없이 검증할 수 있습니다.

```bash
uv sync --group dev
uv run pytest -q
```

```bash
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
```

블렌더가 켜져 있으면 실제 MCP 클라이언트 → 서버 → 소켓 경로 전체를 확인할 수 있습니다:

```bash
uv run python scripts/e2e_socket.py
```

## 내려받은 무료 에셋 부수기

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

| 모델의 문제 | 조각 수 | 부피 보존 | 열린 조각 |
| --- | --- | --- | --- |
| 부품 6개가 서로 박혀 있는 수레 | 40/40 | 1.00 | 0 |
| 뚜껑 없는 그릇(껍데기) | 40/40 | 1.00 | 0 |
| 법선이 뒤집힌 모델 | 40/40 | 1.00 | 0 |
| 벽 두께 5cm + 내용물이 바닥에 붙은 통 | 40/40 | 1.00 | 0 |
| 5cm 짜리 아주 작은 물건 | 40/40 | 1.00 | 0 |
| 면 20,480개짜리 무거운 모델 | 40/40 | 1.00 | 0 |
| 재질 3개가 섞인 모델 | 40/40 | 1.00 | 0 |

`부피 보존`(`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`(조각 접착)는 제약을 수백 개 만들어 굽기가 느려집니다. `glue_neighbors`, `glue_max` 로 줄일 수 있습니다.
- `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](CONTRIBUTING.md)를 보세요. 레시피 하나 = 파일 하나라, 새 효과는 `recipes/` 에 파일을 추가하고 `server.py` 에 도구 하나를 붙이면 됩니다.
참여할 때는 [행동 강령](CODE_OF_CONDUCT.md)을 지켜 주세요.

## 보안

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

## 라이선스

MIT (이 저장소). 블렌더 안 수신기 애드온은 blender-mcp 프로젝트 것이며 그쪽 라이선스를 따릅니다. 함께 설치되는 파이썬 패키지의 라이선스는 [docs/third-party-licenses.md](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").

<!-- setup-steps: uv, addon, connection, client -->
1. **Install uv** (Python runner) — macOS `brew install uv` (doctor prints the Windows/Linux command) → `[OK] uv`
2. **Blender 5.2 + the receiver add-on** — download `addon.py` from [blender-mcp](https://github.com/ahujasid/blender-mcp), then in Blender
   Edit → Preferences → Add-ons → top-right ▾ → **Install from Disk**, and tick it → `[OK] receiver add-on file (blender-mcp)`
3. **Connect in Blender** — in the 3D view press `N` → **BlenderMCP** tab → **Connect to MCP server**. It listens on `localhost:9876` → `[OK] receiver connection`
4. **Register with your AI client** — see [Install](#install) below → `[OK] MCP client registration`

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

```bash
uvx --from git+https://github.com/choisam4u-creator/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](docs/troubleshooting.md)

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

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

### Install

Claude Code:

```bash
claude mcp add -s user blender-fx -e BLENDER_FX_LANG=en -- uvx --from git+https://github.com/choisam4u-creator/blender-fx-mcp blender-fx-mcp
```

Claude Desktop, Codex, Cursor and other MCP clients: add the same command (`uvx --from git+https://github.com/choisam4u-creator/blender-fx-mcp 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/](examples/).
If the tools do not show up, see [troubleshooting](docs/troubleshooting.md#tools-not-visible-in-the-client).

**Check the Blender side first, without an AI** (up to a first render): in a checkout of this repository, open Blender, click Connect, then

```bash
BLENDER_FX_LANG=en uv run python examples/first_render.py   # [1/5] connection → snapshot → building → collapse → preview, then PNG paths
```

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

| Variable | Default | Meaning |
|---|---|---|
| `BLENDER_FX_LANG` | from the locale | `en` or `ko`. Unset: English unless the locale (`LC_ALL`, `LC_MESSAGES`, `LANG`) is Korean; Korean when no locale is set (common for desktop apps), so set it explicitly in GUI client configs |
| `BLENDER_FX_OUT` | `~/blender-fx-output` | where previews, videos, `.blend` files and caches go |
| `BLENDER_FX_HOST` / `BLENDER_FX_PORT` | `localhost` / `9876` | where the receiver listens. Keep it on localhost |
| `BLENDER_FX_TIMEOUT` | `600` | seconds to wait for a quick step. Bake and render tools wait at least 1800 (`render_video` 3600); set a larger value to extend those too |

### 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.

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)](docs/recipes.md#english).

### Tools

| Tool | What it does |
|---|---|
| `doctor` | Checks prerequisites (Python, mcp, uv, Blender, receiver, client registration, output folder). Call it first when something fails |
| `ping_blender` | Checks the connection to the receiver and whether the Blender version is a tested one |
| `list_objects` | Lists mesh names and sizes in the scene (to pick a target) |
| `inspect_mesh` | Diagnoses a model before breaking it: closed or not, volume, concavity, face count, whether repair helps |
| `make_demo_building` | Practice building + ground + camera + lights. `style` (plain/windows), `ground` material |
| `destroy` | Breaks **any mesh** into Voronoi chunks and collapses it with rigid-body physics; repairs the mesh first. `impact`, `material`, `pieces`, `pattern`, `focus`, `glue`, `collision`, `interior`, `dust`, `impact_power`, `time_scale`, `frames`, `seed` and more |
| `explode` | Explosion. With `target` it fractures the object and blows it apart with smoke and fire; otherwise smoke and fire at `at=[x,y,z]` |
| `water` | Liquid with direction, shape and viscosity. `mode` (drop/stream/pool/object), `direction_deg`, `pitch_deg`, `speed`, `liquid` (water/oil/honey/lava/mercury/slime), `viscosity`, `resolution` |
| `splash` | Simple version of `water(mode="drop")` |
| `fire` / `smoke` | Continuous fire / rising smoke. `resolution=0` sizes the domain automatically |
| `particles` | Rain, snow, sparks, ash |
| `wind` | Wind force field that pushes particles, cloth and smoke |
| `ocean` | Animated ocean surface |
| `cloth_flag` | A cloth flag on a pole, waving in the wind |
| `import_model` | Imports glb/gltf/fbx/obj/stl/usd/blend, joins parts, scales and places it on the ground |
| `export_model` | Exports glb/gltf/fbx/obj/**abc**. Alembic keeps per-frame water and chunk motion |
| `camera` | Framing presets wide/medium/closeup/low/high/top/front/side + `angle_deg`, `height`, `lens` |
| `camera_shake` | Camera shake at an impact or explosion |
| `set_look` | Lighting mood day/sunset/night/overcast/studio, procedural sky or your own HDRI |
| `set_ground` | Ground material asphalt/concrete/grass/sand/dirt/snow |
| `snapshot` / `list_snapshots` / `restore` | Save the scene and roll back to it later. Use before risky steps |
| `clear_snapshots` | Delete old snapshots, keeping the newest `keep` (default 5); `before_restore` is always kept |
| `set_timing` | Frame range, fps, slow motion for a frame range or globally |
| `set_physics` | Gravity strength and tilt, substeps, solver iterations, simulation speed |
| `set_render` | Samples, motion blur, resolution, exposure, film look, transparent background |
| `render_preview` | Re-renders the scene. `quality` = `preview` (fast, no smoke/water), `smoke`, `final` |
| `render_video` | Renders the whole scene to mp4 (H.264) |
| `save_blend` | Saves the scene as `.blend` to open and tweak in Blender |
| `clear_caches` | Empties baked caches and cache folders |
| `reset_destroy` | Removes everything this server created and restores the original objects |

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](SECURITY.md) for the risks and private reporting. Contributions: [CONTRIBUTING.md](CONTRIBUTING.md)
and the [Code of Conduct](CODE_OF_CONDUCT.md); how the code fits together: [docs/architecture.md](docs/architecture.md). License: MIT; licenses of the installed dependencies are listed in [docs/third-party-licenses.md](docs/third-party-licenses.md).
