Skip to content
Back to search

blender-mcp-bridge

Automate Blender 3D modeling with AI via MCP — 93 tools for modeling, sculpting, architecture/MEP, materials, and 3D-print prep. Includes Blender Studio: a visual record/replay session editor with a multi-provider AI assistant (Claude, Gemini, OpenRouter) — drive it from n8n, Claude Code, or standalone.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/seehiong--blender-mcp-bridge/badge.svg)](/listings/seehiong--blender-mcp-bridge)

HTML

<a href="/listings/seehiong--blender-mcp-bridge"><img src="/api/listings/seehiong--blender-mcp-bridge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install the Blender addon

The addon is what actually touches Blender, so install it first — full steps under [Installation](#installation). In Blender: **Edit → Preferences → Add-ons → Install**, pick the zipped `blender_mcp_addon` folder, enable it, then press **Start MCP Server** in the sidebar (`N` → *Blender MCP*).

2. Run the bridge

uvx blender-mcp-bridge serve

No clone, no virtualenv. It listens on `http://127.0.0.1:8008/mcp/`.

To hack on it instead, clone the repo and use [`uv`](https://docs.astral.sh/uv/):

uv sync
uv run blender-mcp-bridge serve

3. Point a client at it

This server speaks **HTTP streamable**, not stdio, so clients connect by URL rather than by spawning a command.

**Claude Code** — one command:

claude mcp add --transport http blender http://127.0.0.1:8008/mcp/

**Claude Desktop** — in `claude_desktop_config.json`:

{
  "mcpServers": {
    "blender": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8008/mcp/", "--allow-http"]
    }
  }
}

Claude Desktop launches MCP servers as local processes, so it reaches an HTTP server through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), a small stdio-to-HTTP shim. `npx` downloads it on first run, so the tools may take a few seconds to appear the first time. The shim is required: a direct `{"type": "streamable-http", "url": "..."}` entry is rejected at startup with *"Some MCP servers could not be loaded ... were skipped"* (tested on Claude Desktop for Windows, August 2026).

After editing the file, **quit Claude Desktop completely and reopen it** — it only reads the config at launch, and closing the window leaves it running in the tray. If the config has a JSON syntax error, Claude Desktop reports "Could not load app settings" at startup and runs with *no* MCP servers at all.

> **Not** Settings → Connectors → "Add custom connector". That path sends the URL > to Anthropic's cloud, which then dials the server itself — so it requires a > public HTTPS address and rejects `http://127.0.0.1`. Local servers go in > `claude_desktop_config.json`.

**n8n** — add an *MCP Client* node pointing at the same URL.

Then ask your agent to *"create a 20 mm cube and check whether it is printable"*. It should appear in the Blender viewport — that is the real check. If you get an STL file but nothing happens in Blender, the client never reached the bridge and answered out of its own code instead.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 669 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Blender MCP Bridge
  2. Give an AI agent hands-on control of Blender: build geometry, apply materials,
  3. render, and check that a mesh is printable — 98 tools over the Model Context
  4. Protocol.
  5. Works with **Claude Desktop, Claude Code, n8n**, or any MCP client.
  6. ```bash
  7. uvx blender-mcp-bridge serve
  8. ```
  9. That is the server. It drives a small **addon inside Blender**, which does the
  10. actual work — see [Installation](#installation), a one-time step.
  11. ## System Architecture
  12. Two components, deliberately separate:
  13. 1. **Blender MCP Addon**: a plugin installed *inside* Blender. The local
  14. execution engine — it receives commands and manipulates the 3D scene.
  15. 2. **MCP Bridge Server**: a standalone Python server (`blender_mcp_bridge/`) that acts
  16. as the gateway. MCP clients connect to the Bridge, which forwards commands on
  17. to the running Blender addon.
  18. ```mermaid
  19. graph LR
  20. Client[Claude / n8n / any MCP client] -- "MCP (HTTP Streamable)" --> Bridge[MCP Bridge Server]
  21. Bridge -- "Local TCP socket" --> Addon[Blender MCP Addon]
  22. Addon -- "Python API" --> Blender[Blender Engine]
  23. ```
  24. ## Design rules for printable geometry
  25. `data/design-rules.json` carries 3D-printing design rules — overhang limits, wall
  26. minimums, clearances — extracted from video sources by the sibling
  27. [`print-kb`](https://github.com/seehiong/print-kb) project, each citing the
  28. video and second it came from.
  29. It is plain self-contained JSON: no database, no dependency on that project at
  30. runtime.
  31. Three MCP tools read it, and they answer from the file alone — no LLM, no
  32. embedding model, no network call, and no `print-kb` checkout. A lookup returns in
  33. milliseconds:
  34. | Tool | Use it for |
  35. | --- | --- |
  36. | `check_design` | Describe a part in prose; get the rules bearing on it. |
  37. | `get_design_rules` | Filter by keyword, topic or unit. |
  38. | `list_design_topics` | What the knowledge base covers, before asking it. |
  39. These are the *before-modelling* half of the toolset, and an agent will happily
  40. skip them unless told not to, so say so:
  41. > Call `check_design` for a snap-fit enclosure lid in PLA with a 0.4 mm nozzle,
  42. > tell me the clearances it returns, then model to those numbers.
  43. Two things worth knowing when a dimension matters. Each rule carries a
  44. `value_source`: `source` means the number was stated in the cited video,
  45. `default` means it is a conventional FDM value filled in where the source gave
  46. none. Only about a tenth of the rules are attested, so the tools return **only
  47. those** unless you pass `allow_defaults=true`; when they hold rules back they
  48. report a `withheld` count rather than just returning a shorter list. And the
  49. rules are advisory — they do not check your geometry. `check_mesh_for_printing` verifies a
  50. mesh is manifold, which is a different question from whether two parts fit; for
  51. that, measure the mating faces.
  52. `DESIGN_RULES_PATH` overrides the location; otherwise it is
  53. `data/design-rules.json` when a checkout has one, else the copy bundled in the
  54. wheel. The file is re-read when its mtime changes, so a fresh export lands
  55. without restarting the bridge.
  56. See [`docs/design-rules.md`](docs/design-rules.md) for the schema, how to read it,
  57. and the MCP tools worth building on top.
  58. ## Reference-Guided Mesh Coloring & Multi-Color 3D Printing
  59. The bridge includes an autonomous texturing and coloring pipeline for preparing multi-color 3D models (Bambu Studio / AMS, Prusa MMU):
  60. - **2-Step Viewport Silhouette Lock**: Captures the exact 3D viewport geometry outline before AI image generation, guaranteeing $1:1$ pixel-to-mesh alignment with zero coordinate guessing.
  61. - **Autonomous Color Quantization (`auto_color_from_reference`)**: Automatically samples 2D reference illustrations, clusters colors via K-Means or target filament palettes, and assigns discrete material slots across organic geometry.
  62. - **Continuous UV Baking (`project_and_bake_texture`)**: Seamlessly bakes camera-projected reference textures into a non-overlapping UV atlas.
  63. - **Direct 3MF Export**: Generates slicer-ready `.3mf` multi-material files with verified $1:1\text{ mm}$ physical dimensions.
  64. See [`docs/reference-guided-coloring.md`](docs/reference-guided-coloring.md) and [`docs/tools.md#texturing--multi-color-painting`](docs/tools.md#texturing--multi-color-painting) for complete workflow details.
  65. ## Quick Start
  66. ### 1. Install the Blender addon
  67. The addon is what actually touches Blender, so install it first — full steps
  68. under [Installation](#installation). In Blender:
  69. **Edit → Preferences → Add-ons → Install**, pick the zipped `blender_mcp_addon`
  70. folder, enable it, then press **Start MCP Server** in the sidebar
  71. (`N` → *Blender MCP*).
  72. ### 2. Run the bridge
  73. ```bash
  74. uvx blender-mcp-bridge serve
  75. ```
  76. No clone, no virtualenv. It listens on `http://127.0.0.1:8008/mcp/`.
  77. To hack on it instead, clone the repo and use [`uv`](https://docs.astral.sh/uv/):
  78. ```bash
  79. uv sync
  80. uv run blender-mcp-bridge serve
  81. ```
  82. ### 3. Point a client at it
  83. This server speaks **HTTP streamable**, not stdio, so clients connect by URL
  84. rather than by spawning a command.
  85. **Claude Code** — one command:
  86. ```bash
  87. claude mcp add --transport http blender http://127.0.0.1:8008/mcp/
  88. ```
  89. **Claude Desktop** — in `claude_desktop_config.json`:
  90. ```json
  91. {
  92. "mcpServers": {
  93. "blender": {
  94. "command": "npx",
  95. "args": ["-y", "mcp-remote", "http://127.0.0.1:8008/mcp/", "--allow-http"]
  96. }
  97. }
  98. }
  99. ```
  100. Claude Desktop launches MCP servers as local processes, so it reaches an HTTP
  101. server through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), a small
  102. stdio-to-HTTP shim. `npx` downloads it on first run, so the tools may take a few
  103. seconds to appear the first time. The shim is required: a direct
  104. `{"type": "streamable-http", "url": "..."}` entry is rejected at startup with
  105. *"Some MCP servers could not be loaded ... were skipped"* (tested on Claude
  106. Desktop for Windows, August 2026).
  107. After editing the file, **quit Claude Desktop completely and reopen it** — it
  108. only reads the config at launch, and closing the window leaves it running in the
  109. tray. If the config has a JSON syntax error, Claude Desktop reports "Could not
  110. load app settings" at startup and runs with *no* MCP servers at all.
  111. > **Not** Settings → Connectors → "Add custom connector". That path sends the URL
  112. > to Anthropic's cloud, which then dials the server itself — so it requires a
  113. > public HTTPS address and rejects `http://127.0.0.1`. Local servers go in
  114. > `claude_desktop_config.json`.
  115. **n8n** — add an *MCP Client* node pointing at the same URL.
  116. Then ask your agent to *"create a 20 mm cube and check whether it is printable"*.
  117. It should appear in the Blender viewport — that is the real check. If you get an
  118. STL file but nothing happens in Blender, the client never reached the bridge and
  119. answered out of its own code instead.
  120. ## Configuration
  121. Create a `.env` file in the root directory to customize your setup:
  122. | Variable | Description | Default |
  123. |---|---|---|
  124. | `MCP_BRIDGE_HOST` | Host IP for the MCP Bridge Server | `0.0.0.0` |
  125. | `MCP_BRIDGE_PORT` | Port for the MCP Bridge Server (n8n connects here) | `8008` |
  126. | `BLENDER_ADDON_HOST` | IP where Blender is running (for Bridge to connect to) | `127.0.0.1` |
  127. | `BLENDER_ADDON_PORT` | Port Blender addon is listening on | `8888` |
  128. | `BLENDER_ASSETS_DIR` | Directory to resolve relative textures/HDRIs | (Optional) |
  129. Only needed for the [AI Assistant panel](#ai-assistant-panel-n8n-free-alternative) —
  130. each provider is offered in the UI only if one of its keys is set here (or pasted
  131. into the panel at runtime):
  132. | Variable | Provider |
  133. |---|---|
  134. | `ANTHROPIC_API_KEY` | Anthropic (Claude) |
  135. | `GEMINI_API_KEY` *or* `GOOGLE_API_KEY` | Google (Gemini) |
  136. | `OPENROUTER_API_KEY` | OpenRouter |
  137. ## Installation
  138. ### Method 1: Zip & Install (Recommended)
  139. 1. Zip the `blender_mcp_addon` folder (into `blender_mcp_addon.zip`).
  140. 2. Open Blender.
  141. 3. **For Blender 4.2+**: Go to **Edit** > **Preferences** > **Get Extensions** > Click the dropdown arrow in the top right > **Install from Disk...** and select the `.zip`.
  142. **For Blender 4.0 / 4.1**: Go to **Edit** > **Preferences** > **Add-ons** > **Install...** and select the `.zip`.
  143. 4. Search for "Blender MCP" and enable the checkbox.
  144. ### Method 2: Manual Copy (Developer)
  145. 1. Copy the `blender_mcp_addon` folder to your Blender addons directory (substitute
  146. your actual Blender version for `<version>`, e.g. `4.2` or `5.0`):
  147. - **Windows**: `%USERPROFILE%\AppData\Roaming\Blender Foundation\Blender\<version>\scripts\addons`
  148. - **macOS**: `~/Library/Application Support/Blender/<version>/scripts/addons`
  149. 2. Restart Blender.
  150. 3. Enable "Blender MCP" in Preferences.
  151. > [!NOTE]
  152. > `bl_info` declares a minimum of Blender **4.0**, but STL import/export use the
  153. > `wm.stl_import` / `wm.stl_export` operators introduced in **4.2** — so the
  154. > 3D-print tools need 4.2 or newer. Developed against 5.0.
  155. ## Why a folder instead of a single file?
  156. As the addon grows, a single-file addon becomes unmaintainable — it is now ~6,400
  157. lines across 22 modules. We've split the logic into functional packages (`modeling`,
  158. `materials`, `anim`, etc.) to make it professional, readable, and easier to extend.
  159. ## Usage
  160. ### 1. Start Blender MCP Addon
  161. 1. Open the **N Panel** (press `N` in the 3D Viewport).
  162. 2. Look for the **Blender MCP** tab.
  163. 3. Click **Start MCP Server**.
  164. ### 2. Start the MCP Bridge Server
  165. ```bash
  166. # Standard mode
  167. uv run blender-mcp-bridge serve
  168. # Recording mode (Save all commands to a file)
  169. uv run blender-mcp-bridge serve --record my_session.json --name "Building My House"
  170. ```
  171. The server will start on `http://localhost:8008` with HTTP Streamable endpoint at `/mcp`. It uses detailed logging to show exactly which tools are being called and their results.
  172. ## Bridge Sessions (Record & Playback)
  173. The **Bridge Sessions** feature allows you to record yours or an AI's tool calls and replay them later. This is useful for macros, versioning your creations, or setting up complex scenes consistently.
  174. ### Recording a Session
  175. To record all tool calls made to the bridge while the server is running:
  176. ```bash
  177. uv run blender-mcp-bridge serve --record path/to/session.json --name "My Project" --description "Optional description"
  178. ```
  179. Any tool calls made by n8n or other clients will be automatically saved to the JSON file.
  180. ### Replaying a Session
  181. To playback a previously recorded session:
  182. ```bash
  183. # Default (Stateful - HTTP Streamable) - Recommended for speed
  184. uv run blender-mcp-bridge play path/to/session.json
  185. # Stateless mode (Standard HTTP) - Slower due to handshake overhead
  186. uv run blender-mcp-bridge play path/to/session.json --transport stateless
  187. # Play a single branch (see Session Format below)
  188. uv run blender-mcp-bridge play path/to/session.json --branch sail_rig
  189. # Override session parameters without editing the file (repeatable)
  190. uv run blender-mcp-bridge play path/to/session.json --param box_height=40 --param wall=2.4
  191. ```
  192. > [!NOTE]
  193. > If a session defines branches and `--branch` is omitted, the **first branch plays
  194. > automatically** rather than the whole command list. Any parameter not overridden by
  195. > `--param` falls back to the session's own default from its `parameters` block.
  196. > [!TIP]
  197. > **Performance Note**: Stateful mode is significantly faster for playback because it maintains a persistent connection. Stateless mode requires a full MCP handshake (Initialize/Discover) for *every* individual tool call in the recording, leading to noticeable overhead.
  198. ### Session Format
  199. Sessions are stored as JSON files containing metadata (name, description) and a list
  200. of command objects (tool name, arguments). Studio sessions may also include optional
  201. `parameters` (global, parametric values referenced from command arguments via
  202. `${name}` tokens, including arithmetic expressions) and `branches` (named, jumpable
  203. subsets of the command list). Plain linear sessions with neither key work exactly
  204. as before.
  205. ### Studio (Visual Editor)
  206. Studio is the built-in visual editor for inspecting, editing, and replaying your
  207. recordings — a Vite + React app that talks directly to the MCP Bridge Server.
  208. **Setup** (run from the `studio/` directory, not the project root — it's a separate
  209. npm package from any Node tooling elsewhere in the repo):
  210. ```bash
  211. cd studio
  212. npm install
  213. ```
  214. **Development** — starts a hot-reloading dev server (default `http://localhost:5173`):
  215. ```bash
  216. npm run dev
  217. ```
  218. **Production build** — outputs a static bundle to `studio/dist/`:
  219. ```bash
  220. npm run build
  221. ```
  222. **Preview a production build** — serves the `dist/` output locally to sanity-check it
  223. before deploying:
  224. ```bash
  225. npm run preview
  226. ```
  227. Both `dev` and `build` first run `npm run prebuild-assets`, which regenerates two sets
  228. of static assets — you don't invoke these directly:
  229. | Script | What it does |
  230. |---|---|
  231. | `sync-community` | Copies every `community/*/session.json` into `studio/public/community/` and writes an `index.json` manifest, so the **Load Community Sample** dropdown can fetch a static list (static hosts like GitHub Pages can't do directory listings). Also **prunes** copies whose source folder is gone, so deleting or renaming a project doesn't leave a stale session in the build. |
  232. | `gen-demo-tools` | Regenerates the static tool catalog used by [Demo Mode](#demo-mode-no-bridge-required). |
  233. The copies are generated rather than committed, so they can never drift from the
  234. `community/` source of truth. Add a new community folder with a `session.json` and it
  235. shows up in the dropdown on the next `npm run dev`/`build` — no manual step.
  236. Once built, the Bridge Server also serves Studio directly at **`http://localhost:8008/studio/`**
  237. (no separate `npm run dev` needed) — if `studio/dist/` doesn't exist yet, that route
  238. returns a short message with the build command instead of failing.
  239. Studio talks directly to the MCP Bridge Server over HTTP (same `/mcp` endpoint used
  240. by n8n), so **the Bridge Server must be running** (`uv run blender-mcp-bridge serve`)
  241. for Studio to connect. It auto-detects the bridge on `localhost:8008` then
  242. `localhost:8000`.
  243. In Studio you can:
  244. - Edit session metadata (Name, Description, AI Model).
  245. - Filter commands by tool name.
  246. - **Add & Edit Commands**: an interactive modal with schema validation to discover
  247. tools, safely modify arguments, or add entirely new steps.
  248. - Edit tool arguments directly in the JSON editor cards, or toggle to a whole-session
  249. **Guided / JSON view** for bulk edits with a command outline for quick navigation.
  250. JSON mode includes live parametric-expression linting (undefined `${param}`
  251. references, divide-by-zero, and syntax errors are flagged inline and block Apply).
  252. - Reorder or delete commands, and replay them from the **ActionBar** (Play All / Play
  253. / Play to Active / Stop / Undo / Redo / Reset / Clear Scene), always visible at the
  254. top of the **Command Timeline** dock regardless of whether the timeline's diagram
  255. is expanded or collapsed.
  256. - Define **global parameters** (`${name}` tokens, including arithmetic expressions
  257. like `${box_height} / 2`) so command arguments stay reusable across resizes/edits.
  258. - Define **branches** — named, non-contiguous ranges of the command list you can jump
  259. between and run independently (e.g. a "plain" feature vs. a "with extra part"
  260. feature sharing a common base) — via the Branches panel's click-to-pick range
  261. builder, then pick and run one from the ActionBar's branch dropdown.
  262. - **Command Timeline**: a horizontal diagram of command order and branch ranges at
  263. the bottom of the window (resizable, click a tick to jump to that command). Long
  264. branch ranges can be collapsed into a single condensed marker (click a branch's
  265. range bar, Excel-style column grouping) to keep the diagram readable in sessions
  266. with many commands.
  267. - **Export JSON** to save your changes to a new file.
  268. ### AI Assistant Panel (n8n-free Alternative)
  269. Studio also includes a standalone **AI Assistant** — a resizable chat drawer (toggle
  270. with the header's 🤖 button) that lets you drive Blender with natural language,
  271. without setting up n8n at all. It talks directly to an LLM provider through the
  272. Bridge Server's `/assistant/*` endpoints, using the same MCP tool set as everything
  273. else in this project.
  274. - **Multi-provider**: switch between **Anthropic (Claude)**, **Google (Gemini)**, and
  275. **OpenRouter** (which unlocks most open models, including free ones) via a dropdown.
  276. Custom model IDs can be saved per provider and persist across restarts.
  277. - **API keys**: read from the Bridge's environment by default; a key pasted into the
  278. panel (stored only in your browser) overrides it — useful when the bridge host has
  279. no key configured, or when experimenting with a different provider.
  280. - **Load STL**: upload a model file directly from the panel; it's saved under
  281. `BLENDER_ASSETS_DIR/uploads/` and imported into the scene automatically.
  282. - **Vision-verified agent loop**: when a tool call produces a screenshot or render,
  283. the image is attached to the conversation (in each provider's native image format),
  284. so the model can actually *see* the result of its own edits — catching floating or
  285. misaligned geometry that numeric verification alone would miss. Models without
  286. vision support get a graceful fallback to numeric-only verification.
  287. - **Recordable**: like every other client, assistant-driven tool calls flow through
  288. the same session recorder (`serve --record`), so an AI conversation produces a
  289. replayable `session.json`.
  290. The community [Benchy sail rig](community/benchy/README.md#branch-sail_rig--a-decorative-square-rig-sail)
  291. was designed almost entirely through this panel — including the print-design fixes
  292. (diamond-profile spars, flush bar tips) discovered by looking at real slicer output.
  293. ### Demo Mode (No Bridge Required)
  294. **[Live demo on GitHub Pages](https://seehiong.github.io/blender-mcp-bridge/)** —
  295. auto-deployed by [`.github/workflows/deploy-studio.yml`](.github/workflows/deploy-studio.yml)
  296. on every push to `main` that touches `studio/`.
  297. > [!NOTE]
  298. > **The connection check always runs in *your* browser, against `localhost` —
  299. > never against the page author's machine.** Studio's connection probe
  300. > (`studio/src/lib/api.js`) always targets `http://localhost:8008` (then `:8000`),
  301. > regardless of where the Studio page itself is hosted. So:
  302. > - If **you** have your own Bridge Server running locally, the hosted Pages demo
  303. > will genuinely connect to it and drive **your own** Blender instance — hosting
  304. > the UI once on Pages doesn't require running it locally too.
  305. > - If you **don't** have a bridge running, the header shows **"Offline"** and a
  306. > **"▶ Try Demo Mode"** button appears. Demo mode is always opt-in, never
  307. > automatic — a genuinely offline bridge is never silently mistaken for a
  308. > working connection.
  309. >
  310. > In all cases, no one visiting the Pages demo can ever reach *another visitor's*
  311. > Blender instance — the browser only ever talks to `localhost` on the machine
  312. > it's running on.
  313. Once in Demo Mode:
  314. - Loads a static tool catalog (`studio/src/lib/demoTools.js`) so the guided forms,
  315. schema validation, and the **+ New Command** / **Edit Command** modals all work
  316. normally.
  317. - Simulates tool execution and playback (`studio/src/lib/demoApi.js`) instead of
  318. calling a real bridge — good for exploring the session editor, branches, and the
  319. Command Timeline with any of the [community sample sessions](community/README.md).
  320. What demo mode **doesn't** do: it can't talk to Blender, so nothing is actually
  321. rendered or exported, and the **AI Assistant panel is disabled** while it's active
  322. (it needs a live bridge and a real model API to do anything meaningful). Exit demo
  323. mode any time with the header's "✕ Exit Demo" button.
  324. ### 3. Configure n8n Workflow
  325. ![n8n Design](docs/images/blender-mcp-for-n8n.png)
  326. 1. Add **MCP Client Tool** node
  327. 2. Configure:
  328. - **HTTP Streamable Endpoint**: `http://localhost:8008/mcp`
  329. - **Authentication**: None
  330. - **Tools to Include**: All
  331. 3. Connect to an **AI Agent** node
  332. ### 4. Development: Updating & Applying Changes
  333. If you modify the addon code or the MCP server logic, follow these steps to ensure changes are applied:
  334. 1. **Reload Scripts**: In Blender, press `F3` and type **"Reload Scripts"** (or use the shortcut `Alt + R` if configured).
  335. 2. **Restart Blender Server**: In the N-Panel, click **Stop MCP Server** and then **Start MCP Server** again.
  336. 3. **Restart Python Server**: Stop and restart the server with `uv run blender-mcp-bridge serve`.
  337. > [!IMPORTANT]
  338. > All Blender operations now run on the main thread via a command queue, ensuring stability and preventing dependency graph errors.
  339. ## Available Tools
  340. The server exposes **106 tools** — 103 forwarded to Blender, plus 3 answered locally
  341. from the design-rule export. The full reference with descriptions and
  342. parameters lives in [docs/tools.md](docs/tools.md).
  343. | Category | Tools | Highlights |
  344. |---|---|---|
  345. | Modeling | 48 | primitives, booleans, modifiers (incl. `BEVEL` with edge-selection control, `SCREW` lathe/spin and `SIMPLE_DEFORM` twist/bend/taper), `create_curve` 2D drafting (lines + true arcs), `create_watertight_plate`, room shells |
  346. | Reference Coloring & Texturing | 7 | `import_model_with_reference`, `setup_reference_camera`, `color_faces_by_rule` (AMS/MMU material assignment), `project_and_bake_texture` (Cycles bake), `get_mesh_color_slots`, `separate_mesh_by_material`, `get_viewport_screenshot` |
  347. | 3D-Print Preparation | 7 | `check_mesh_for_printing`, `repair_mesh`, `apply_voxel_remesh`, `add_model_base` (plinths/stands), import STL/OBJ/FBX/GLB, export STL/3MF/GLB |
  348. | Materials | 7 | PBR materials, hex colors, texture assignment |
  349. | Collections | 7 | create/move/organize collections |
  350. | Sculpting | 7 | brush-based sculpt strokes and remeshing |
  351. | Scene & Diagnostics | 4 | scene/object info, viewport screenshots, distances |
  352. | Animation | 4 | keyframes, playback range |
  353. | Lighting & World | 3 | lights, light editing, HDRI/sky/color world background |
  354. | Camera | 3 | cameras, look-at, active camera |
  355. | Rendering | 4 | engine setup, frame renders, `generate_views` one-call top/front/side/iso previews |
  356. | History / Undo | 2 | undo / redo |
  357. | Design Rules | 3 | `check_design`, `get_design_rules`, `list_design_topics` — answered locally from the print-kb export, never forwarded to Blender |
  358. ## Example Usage in n8n
  359. ### Example Interaction
  360. **User:** "Create a red metallic sphere at position [0, 0, 2]"
  361. > **Assistant:** Perfect! I've successfully created a red metallic sphere at position [0, 0, 2]. Here's what was done:
  362. > - Created a sphere named "RedMetallicSphere" with a radius of 1 unit at coordinates [0, 0, 2]
  363. > - Applied a red metallic material using a polished metal preset with a red base color (#FF0000)
  364. >
  365. > The sphere is now ready in your Blender scene with a shiny red metallic appearance.
  366. **User:** "Duplicate the red sphere, move it to [5, 0, 2], and change its color to blue"
  367. > **Assistant:** Perfect! I've successfully completed all the tasks:
  368. > - Duplicated the red sphere and created a new object named "BlueMetallicSphere"
  369. > - Moved it to position [5, 0, 2]
  370. > - Changed the material to blue metallic with a polished metal finish
  371. >
  372. > You now have two metallic spheres in your scene: RedMetallicSphere at [0, 0, 2] (red) and BlueMetallicSphere at [5, 0, 2] (blue).
  373. **User:** "Select both the original red sphere and the duplicate, then add a Subdivision modifier to both"
  374. > **Assistant:** Excellent! I've successfully:
  375. > - Selected both spheres (RedMetallicSphere and BlueMetallicSphere)
  376. > - Added a Subdivision Surface modifier (SUBSURF) to both objects with 2 levels of subdivision
  377. >
  378. > This modifier will smooth and refine the geometry of both spheres, giving them a more polished and rounded appearance.
  379. **User:** "Add a torus with minor_radius 0.1 and major_radius 25 at [2, 0, 0]"
  380. > **Assistant:** Perfect! I've successfully created a torus with the specifications you requested:
  381. > - **Name:** Torus
  382. > - **Position:** [2, 0, 0]
  383. > - **Major radius:** 25 (distance from center to center of the tube)
  384. > - **Minor radius:** 0.1 (thickness of the tube)
  385. >
  386. > This creates a very thin, large torus - essentially a large ring with a thin profile. It's now in your Blender scene alongside the two metallic spheres!
  387. ## Community Showcase
  388. Real parts, modelled by an agent driving this bridge. Two are in this repo so
  389. you can try one immediately:
  390. | project | what it shows |
  391. |---|---|
  392. | [**Cable Comb**](community/cable_comb/README.md) | a two-part pin joint built to measured 3D-printing design rules |
  393. | [**Stackable Bin**](community/stackable_bin/README.md) | a parametric bin that nests into the one below it |
  394. ```bash
  395. blender-mcp-bridge play community/cable_comb/session.json
  396. ```
  397. The full gallery — the benchy, architectural scenes, the modular profile rack,
  398. threaded bolts, the Y-zipper teardown and more — lives in its own repository, so
  399. installing the bridge does not mean downloading a print archive:
  400. **[blender-mcp-community](https://github.com/seehiong/blender-mcp-community)**
  401. > [!TIP]
  402. > **Share your work**: recorded something good? The
  403. > [contribution guide](https://github.com/seehiong/blender-mcp-community#how-to-share-your-project)
  404. > covers how to record, clean and submit a session.
  405. ## ⚡ POWER TIPS: Avoiding Rate Limits
  406. To prevent n8n or LLM "Too many requests" errors, follow these **Stateless Power Working** rules:
  407. ### 1. Avoid Selection-Based Workflows
  408. ❌ **Slow (4+ turns):** `select_by_pattern('Wall_*')` → `create_material('M_Gray')` → `assign_material()`
  409. ✅ **Fast (1 turn):** `create_material(name='M_Gray', pattern='Wall_*')`
  410. ### 2. Group by Collections
  411. ❌ **Unreliable:** Selecting individual objects.
  412. ✅ **Reliable:** `create_material(name='M_Glass', collection='Cutters')`
  413. ### 3. Bulk creation
  414. If you need 10 objects, don't create them one-by-one. Use `duplicate_object` with `count` or `apply_modifier` with `ARRAY`.
  415. ## Architecture & Technical Design
  416. This project uses the modular `blender_mcp_bridge/` package to ensure maintainability:
  417. ```mermaid
  418. graph TD
  419. A[main.py] --> B[server.py]
  420. B --> C[tools/ package]
  421. C --> D[modeling/ package]
  422. C --> E[scene.py]
  423. C --> F[materials.py]
  424. B --> G[connection.py]
  425. B --> I[sessions.py]
  426. B --> J[assistant.py]
  427. I --> K[params.py]
  428. A --> L[config.py]
  429. G --> H[Blender]
  430. ```
  431. ### Transport Model
  432. Although the MCP specification supports persistent HTTP Streamable sessions, many clients (including n8n) currently operate in a stateless execution model, performing:
  433. `Initialize` → `Discover Tools` → `Call Tool` → `Close`
  434. for each interaction.
  435. The server uses the official **HTTP Streamable** transport introduced in MCP SDK 1.8.0+, which supports both stateful sessions and stateless requests.
  436. ### The Stateless Fallback Mechanism
  437. To ensure reliability across clients, the server implements a robust fallback strategy:
  438. 1. **Protocol Resilience**: If no active HTTP Streamable session exists, the server transparently handles standard JSON-RPC requests over HTTP.
  439. 2. **Execution Isolation**: Each tool call is processed independently, preventing session corruption or deadlocks.
  440. 3. **Visual Success Indicators**: Tool responses are prefixed with `✓` when successful. This helps the AI Agent’s conversational memory confirm task completion and avoid unintended re-execution loops.
  441. 4. **Clear State Boundaries**: Persistent state is intentionally separated:
  442. - 🧠 **Conversation memory** → AI Agent (n8n Simple Memory)
  443. - 🧩 **Scene state** → Blender runtime
  444. - 🚀 **MCP server** → Stateless execution bridge
  445. ### Architecture Diagram
  446. ```
  447. n8n AI Agent
  448. ↓
  449. MCP Client (HTTP Streamable / JSON-RPC)
  450. ↓
  451. MCP Server (ASGI)
  452. ↓
  453. TCP Socket Bridge
  454. ↓
  455. Blender Addon (Main Thread Queue)
  456. ↓
  457. Blender Scene (Persistent State)
  458. ```
  459. ## Testing
  460. We use an integrated test suite to verify Blender tools and layout scenarios.
  461. ```bash
  462. # Run the Arch layout test
  463. uv run python tests/run_integration.py run --scenario arch
  464. # Run the standard functional grid test
  465. uv run python tests/run_integration.py run --scenario grid
  466. # Run the 3D Printing tool verification test
  467. uv run python tests/run_integration.py run --scenario print
  468. # Run the Filament Name Tag & Stand generation test
  469. uv run python tests/run_integration.py run --scenario filament_tag
  470. ```
  471. ### Scenarios
  472. | Scenario | Key | Description |
  473. |---|---|---|
  474. | Grid Layout | `grid` | Functional grid test covering all tool categories |
  475. | Arch Layout | `arch` | Architectural scene generation test |
  476. | Print Validation | `print` | 3D printing workflow: units, mesh repair, export |
  477. | Filament Tag | `filament_tag` | Generates a 4-piece modular filament name tag & clip system (NameTagCard, AMSClip, StickonHolder, DeskStand) |
  478. See the [Integration Testing Guide](docs/integration_tests.md) for full details on verification and benchmarking.
  479. ### Unit Tests
  480. The scenarios above need a live Blender. Two pure-Python suites don't — they cover the
  481. session record/replay round-trip and schema hygiene across all 94 tool definitions:
  482. ```bash
  483. uv run --with pytest python -m pytest tests/ -q
  484. ```
  485. See the [Unit Testing Guide](docs/unit_tests.md). Note these are not run by CI, which
  486. covers only ruff and mypy.
  487. ## Code Quality & Standards
  488. We enforce code quality standards using [Ruff](https://docs.astral.sh/ruff/) and [Mypy](https://mypy.readthedocs.io/). These are run automatically on GitHub Actions CI.
  489. To run these checks locally:
  490. ```bash
  491. # 1. Format code (strict black-compatible formatting)
  492. uv run ruff format blender_mcp_bridge/ tests/ blender_mcp_addon/
  493. # 2. Run linter and check code complexity (McCabe <= 12)
  494. uv run ruff check blender_mcp_bridge/ tests/ blender_mcp_addon/
  495. # 3. Auto-fix standard lint issues
  496. uv run ruff check blender_mcp_bridge/ tests/ blender_mcp_addon/ --fix
  497. # 4. Run static type checking
  498. uv run mypy blender_mcp_bridge/
  499. ```
  500. ## Troubleshooting
  501. **Server won't start**: Install dependencies with `uv sync`
  502. **Connection failed**: Ensure Blender MCP addon is running on port 8888.
  503. **Dependency Graph Error**: If you see this, ensure you have the latest `blender_mcp_addon` package which implements the main-thread command queue.
  504. **Tools not appearing in n8n**: Check the HTTP Streamable endpoint URL is correct (`http://localhost:8008/mcp`)
  505. ## Acknowledgments
  506. This project was inspired by [blender-mcp](https://github.com/ahujasid/blender-mcp) by [ahujasid], which demonstrated the potential of MCP servers for Blender automation.
  507. ## License
  508. MIT License - See LICENSE file for details

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.