Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(blender-mcp): drive a local headless Blender from any MCP client

nirholasbb2a4fefd08a
diff --git a/.mcp.json b/.mcp.json
index 056153b6e..50590ac04 100644
--- a/.mcp.json
+++ b/.mcp.json
@@ -21,6 +21,10 @@
"MCP_SVM_PAYMENT_ADDRESS": "${MCP_SVM_PAYMENT_ADDRESS}"
}
},
+ "blender": {
+ "command": "node",
+ "args": ["packages/blender-mcp/src/index.js"]
+ },
"atelier": {
"type": "http",
"url": "https://app.useatelier.ai/mcp"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f78c6a1bd..809e91a1d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,10 @@
Public history for [three.ws](https://three.ws), newest first. New pages come from `added` dates in data/pages.json; everything else is curated in data/changelog.json. Also available as [JSON](https://three.ws/changelog.json) and [RSS](https://three.ws/changelog.xml), live at [three.ws/changelog](https://three.ws/changelog).
+## 2026-09-07
+
+- **Point an AI agent at the Blender on your own machine**: A new MCP server drives the Blender you already have installed, with no GUI open and no add-on to install first. An assistant can now read a 3D file and tell you what is actually in it (objects, triangle counts, materials, bones, animations, real-world size), convert between GLB, glTF, FBX, OBJ, STL, PLY, Collada, Alembic, USD and .blend in either direction, render a preview image of a bare asset file that arrives with no camera or lighting of its own, and run a Blender Python script to do the things no single tool covers, like halving a mesh's triangle count and exporting the result in one step. It also reaches back into three.ws: describe something in a sentence and the free text-to-3D lane generates it and opens it in Blender. Blender runs in the background, one process per request, so it works the same on a laptop, a server, or in CI. `[feature, sdk]`
+
## 2026-09-05
- **Docs · Pocket Console** (`/docs/pocket`): How the /pocket handheld works: the D-pad and gamepad controls, the three cartridges, the URL params that make a share link, and the one iframe that puts a live 3D agent console on any site.
@@ -21,6 +25,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **One command drops a three.ws prop, character or motion clip into your project**: npx @three-ws/assets search wooden chair finds it, and npx @three-ws/assets add object:painted_wooden_chair_01 downloads the model into your public folder and prints the tag that renders it, already pointing at your local copy rather than our CDN. Your site keeps working even if we do not. The catalog behind it is the same one the AI tools read: 511 CC0 props, 107 rigged characters and 2,874 motion clips, searchable in one place instead of three separate galleries. It is also a plain HTTP endpoint now, GET /api/catalog, free and open to any origin, so a build script or a site that is not using an AI client can read it too. Adding an asset twice changes nothing the second time, and a file you edited afterwards is never overwritten without asking. Every object is CC0, and the license of anything that is not travels with it in the output. (`/docs/api-reference`) `[feature, sdk]`
- **Seven background jobs that were never running now run**: Seven scheduled jobs were declared in the platform config but had no matching job on the scheduler, so they had never fired: the companion poll, feedback triage, print-order syncing, the home health alert, the home-relay sweep, web-variant generation for the forge, and the oracle refit. Three of them shipped with live features behind them, which meant those features quietly did nothing on a timer. All seven are now created and enabled on their declared schedules, and a drift check confirms every declared job exists and matches. `[fix, infra]`
- **The site header now stays put when you scroll**: The navigation bar was set to stick to the top of the window but never actually did: it scrolled away with the page on every route, at every screen size, so reaching the menu meant scrolling all the way back up. The bar was mounted inside a wrapper exactly its own height, and a sticky element can only travel inside its parent, so it had nowhere to go. The header now stays on screen wherever you scroll, on phones and desktop alike. `[fix, improvement]`
+- **The VS Code extension now animates, refines, optimizes and reviews your models, and checks your embeds**: Open a rigged model in VS Code, press Animate, and pick from the same 2,800-clip motion library the site uses: the clip is retargeted onto that model's own skeleton right in the editor, and Bake clip writes it into a copy of the file so it plays in Unity, Unreal or Blender too. Describe a motion in words and the GPU fleet samples one for you. Refine takes a change like make it metallic and generates a new version anchored to the current one, keeping the version history. Optimize runs the platform's web passes on your machine and tells you what it saved. Compare pulls the committed version straight out of git, opens both side by side, and writes a structural review of what changed. Check quality asks a vision model to score the render and hands its fix straight to Refine. A turntable GIF button makes README material in one click. And in HTML, React, Vue, Svelte, Astro and Markdown files the editor now checks agent-3d tags as you type: a missing source or size, an unpinned library script, a stale integrity hash the browser would refuse, a misspelt attribute, each with a one-click fix, plus hovers and completions for every attribute. (`/docs/vscode`) `[feature, sdk, improvement]`
- **Walk up to an IRL agent, talk to it out loud, and stand it on your floor in AR**: Tap any agent you discover on IRL and the card now leads with Talk and View in AR. Talk is a real conversation with the agent standing in front of you: hold the mic and speak, or type. It answers in its own persona, out loud in its voice (its cloned voice when it has one), and the 3D model's mouth moves with the words while it keeps breathing. Press the mic while it is talking to interrupt it. View in AR works on anyone's agent, not only your own: iPhone opens it in Quick Look on the real floor, animated, with a banner that brings you back to the conversation; Android phones with ARCore anchor it to the detected floor right inside the page, tap to place and pinch to size; every other device opens the AR launcher. Owners see a new "talked with your agent" event in their IRL feed when someone starts a conversation. The transcript stays between the visitor and the agent. (`/irl`) `[feature]`
- **Your agent now lives in a handheld console you can put on any website**: The new Pocket Console at /pocket is a real handheld with a real 3D agent inside the screen. The D-pad walks it, A waves, B jumps, START swaps between the agent walking, its live stats, and a menu of every public agent you can slot in like a cartridge, and L and R flip through them. It takes keyboard, touch and a plugged-in game controller. Four shell finishes, four scenes, and the whole state travels in the link, so what you share is the device exactly as you left it. Add chrome=off and one iframe puts the console, your agent included, on your own site: transparent background, no sign-in, no SDK, no API key. (`/pocket`) `[feature]`
diff --git a/STRUCTURE.md b/STRUCTURE.md
index f5ea821f8..b78bc0807 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -337,6 +337,7 @@ packages/alibaba-cloud-mcp/ → @three-ws/alibaba-cloud-mcp (MCP server — A
packages/three-token-mcp/ → @three-ws/three-token-mcp (MCP server — $THREE token tools)
packages/threews-avatar-mcp/ → @three-ws/threews-avatar-mcp (MCP server — three.ws avatar ops)
packages/scene-mcp/ → @three-ws/scene-mcp (MCP server — text→3D diorama scenes)
+packages/blender-mcp/ → @three-ws/blender-mcp (MCP server - drives a LOCAL headless Blender: inspect/convert/render/script 3D files, plus text-to-3D import)
packages/assistant-mcp/ → @three-ws/assistant-mcp (MCP server — generate a 3D avatar assistant widget embed)
packages/vanity-mcp/ → @three-ws/vanity-mcp (MCP server — Solana vanity bounty market + rarity gallery)
packages/naming-mcp/ → @three-ws/naming-mcp (MCP server — .sol resolve + *.threews.sol identity availability)
diff --git a/data/changelog.json b/data/changelog.json
index daca20602..33215ea91 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -26759,6 +26759,15 @@
"improvement"
],
"link": "/demo"
+ },
+ {
+ "date": "2026-09-07",
+ "title": "Point an AI agent at the Blender on your own machine",
+ "summary": "A new MCP server drives the Blender you already have installed, with no GUI open and no add-on to install first. An assistant can now read a 3D file and tell you what is actually in it (objects, triangle counts, materials, bones, animations, real-world size), convert between GLB, glTF, FBX, OBJ, STL, PLY, Collada, Alembic, USD and .blend in either direction, render a preview image of a bare asset file that arrives with no camera or lighting of its own, and run a Blender Python script to do the things no single tool covers, like halving a mesh's triangle count and exporting the result in one step. It also reaches back into three.ws: describe something in a sentence and the free text-to-3D lane generates it and opens it in Blender. Blender runs in the background, one process per request, so it works the same on a laptop, a server, or in CI.",
+ "tags": [
+ "feature",
+ "sdk"
+ ]
}
]
}
diff --git a/data/pages.json b/data/pages.json
index 50f9f5af9..fa8fa5aa4 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -4941,6 +4941,13 @@
"priority": 0.6,
"changefreq": "monthly"
},
+ {
+ "path": "/docs/blender-mcp",
+ "title": "Docs · Blender MCP",
+ "description": "Give an AI agent the Blender on your own machine, headless: inspect, convert, render and script 3D files, plus text-to-3D straight into a scene.",
+ "priority": 0.6,
+ "changefreq": "monthly"
+ },
{
"path": "/docs/spatial-mcp",
"title": "Docs · Spatial MCP",
diff --git a/docs/blender-mcp.md b/docs/blender-mcp.md
new file mode 100644
index 000000000..2eb50e26b
--- /dev/null
+++ b/docs/blender-mcp.md
@@ -0,0 +1,220 @@
+# Blender MCP
+
+`@three-ws/blender-mcp` hands an AI assistant the Blender installed on your own machine. It speaks the [Model Context Protocol](https://modelcontextprotocol.io) over stdio, and it drives Blender in background mode: no GUI session has to be open, no add-on has to be installed into Blender first, and nothing stays resident between calls.
+
+That makes it the piece that sits under the three.ws pipeline rather than beside it. Forge generates a model; this reads it, converts it, previews it, and edits it, using the most complete format bridge that exists offline.
+
+---
+
+## What it is for
+
+| You want to | Tool |
+|---|---|
+| Know what is actually inside a file a client sent you | `blender_scene_info` |
+| Turn an FBX or a USD into a web-ready GLB (or the reverse) | `blender_convert` |
+| See a model without opening anything | `blender_render` |
+| Do something no single tool covers: decimate, join, rename bones, bake | `blender_run_python` |
+| Generate an asset from a sentence and open it | `blender_forge_import` |
+| Find out why one of the above failed | `blender_info` |
+
+---
+
+## Requirements
+
+- **Node.js 20+**
+- **Blender 3.0 or newer**, installed locally: [blender.org/download](https://www.blender.org/download/), or your package manager.
+
+If Blender is not on `PATH`, set `BLENDER_PATH` to the executable. On macOS that is `/Applications/Blender.app/Contents/MacOS/Blender`.
+
+Some Linux distribution packages ship Blender without the Python modules its glTF add-on needs. `blender_info` tells you what the local build can really do, which turns that class of problem into one clear answer instead of a confusing failure inside an unrelated call.
+
+---
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add blender -- npx -y @three-ws/blender-mcp
+```
+
+In this repository the server is already declared in [`.mcp.json`](../.mcp.json) and runs straight from the working tree:
+
+```json
+{
+ "mcpServers": {
+ "blender": {
+ "command": "node",
+ "args": ["packages/blender-mcp/src/index.js"]
+ }
+ }
+}
+```
+
+### Claude Desktop / Cursor
+
+```json
+{
+ "mcpServers": {
+ "blender": {
+ "command": "npx",
+ "args": ["-y", "@three-ws/blender-mcp"],
+ "env": { "BLENDER_PATH": "/Applications/Blender.app/Contents/MacOS/Blender" }
+ }
+ }
+}
+```
+
+---
+
+## Tools
+
+### `blender_info`
+
+No arguments. Reports the executable path, Blender version, bundled Python version, the render engines that are genuinely usable on this build, and the import/export extensions it supports. Read-only.
+
+Call it first whenever anything else fails: it separates "Blender is missing" from "this build cannot do that" from "the file is wrong".
+
+### `blender_scene_info`
+
+| Argument | Type | Notes |
+|---|---|---|
+| `input` | string, required | Path to the file. Absolute, or relative to the server's working directory. |
+| `include_objects` | boolean | Include the per-object breakdown. Set `false` on huge scenes for totals only. Default `true`. |
+
+Opens a `.blend`, or imports any supported format into an empty scene, and describes it: objects with type, parent, dimensions, modifiers, materials and UV layers; **evaluated** triangle and vertex counts, so a subdivision modifier is counted as what it renders, not what it stores; armature bone names; animation actions with frame ranges; and world-space bounds. The file is never modified.
+
+```
+blender_scene_info { "input": "~/assets/character.fbx" }
+```
+
+### `blender_convert`
+
+| Argument | Type | Notes |
+|---|---|---|
+| `input` | string, required | Source file. |
+| `output` | string | Destination. Its extension picks the format. Defaults to a `.glb` in the workdir. |
+| `apply_modifiers` | boolean | Bake modifiers into the exported geometry. Default `true`. |
+| `scale` | number | Uniform scale baked into the export, e.g. `0.01` for centimetres to metres. |
+
+Both sides accept `.glb`, `.gltf`, `.fbx`, `.obj`, `.stl`, `.ply`, `.dae`, `.abc`, `.usd`, `.usda`, `.usdc`, `.usdz`, `.x3d`, and `.blend`, as far as the local build supports them: several Linux distribution packages ship Blender without USD, Collada, or Alembic. `blender_info` lists what yours really has, and asking for one it lacks fails immediately with `format_unsupported` rather than part way through an export.
+
+```
+blender_convert { "input": "character.fbx", "output": "character.glb", "scale": 0.01 }
+```
+
+### `blender_render`
+
+| Argument | Type | Notes |
+|---|---|---|
+| `input` | string, required | File to render. |
+| `output` | string | Destination PNG. Defaults into the workdir. |
+| `engine` | enum | `auto` (default), `CYCLES`, `BLENDER_EEVEE`, `BLENDER_WORKBENCH`. |
+| `samples` | integer | Default `32`, enough for a preview. |
+| `resolution` | `[width, height]` | Default `[960, 960]`. |
+| `transparent` | boolean | Transparent background instead of the world. Default `false`. |
+
+An asset file usually carries no camera and no lights, which is why rendering one straight out of a converter normally produces a black square. This tool fills both in: it creates a camera and frames it to the geometry's bounding sphere, and adds a key light and a lit world. A scene that already has its own camera and lighting is rendered exactly as authored, and the response says which of the two happened (`camera_created`, `lights_created`).
+
+`auto` picks Cycles, which renders on CPU and therefore works in a container. EEVEE is far faster but needs a real GPU context.
+
+### `blender_run_python`
+
+| Argument | Type | Notes |
+|---|---|---|
+| `code` | string, required | Python to execute. `bpy`, `math` and `Vector` are already imported. |
+| `input` | string | File to open first. Omit to start from an empty scene. |
+| `output` | string | Export the result here afterwards; the extension picks the format. |
+| `apply_modifiers` | boolean | Apply modifiers on that export. Default `true`. |
+
+Anything printed comes back as `stdout`. Assigning a JSON-serializable value to a variable named `result` returns it as structured data alongside the post-run scene counts.
+
+```
+blender_run_python {
+ "input": "character.glb",
+ "output": "character-lod1.glb",
+ "code": "import bpy\nfor obj in bpy.data.objects:\n if obj.type == 'MESH':\n obj.modifiers.new('Decimate', 'DECIMATE').ratio = 0.5\nresult = {'meshes': len([o for o in bpy.data.objects if o.type == 'MESH'])}"
+}
+```
+
+This tool runs caller-supplied code with the server's own permissions. See [Security](#security).
+
+### `blender_forge_import`
+
+| Argument | Type | Notes |
+|---|---|---|
+| `prompt` | string, required | One subject, e.g. `a weathered brass diving helmet`. |
+| `output` | string | Destination. `.glb` keeps the generated bytes untouched; any other extension converts on the way in. |
+| `tier` | enum | `draft`, `standard` (default), `high`. |
+| `lane` | enum | `image` (default, free), `geometry` (Meshy/Tripo, needs a key), `sketch`. |
+| `backend` | string | Pin a backend. Omit to let the deployment choose for the tier. |
+| `aspect_ratio` | enum | Reference image ratio. Default `1:1`. |
+
+Runs the public [`/api/forge`](./3d-api.md) pipeline: the default image lane (FLUX to TRELLIS) is free and needs no key, wallet, or account. When the output asks for a non-GLB format, the untouched GLB is kept beside it as `<name>.source.glb`, because conversion is lossy for some targets and the original is what the rest of the three.ws pipeline consumes.
+
+Generation runs on a shared GPU lane and typically takes tens of seconds to a couple of minutes.
+
+```
+blender_forge_import { "prompt": "a weathered brass diving helmet", "output": "helmet.blend" }
+```
+
+---
+
+## How a call works
+
+Every tool call spawns one process:
+
+```
+blender -b --factory-startup -noaudio --python src/py/runner.py -- <job.json> <result.json>
+```
+
+Three design decisions are worth knowing, because they are what makes the tools predictable:
+
+1. **`--factory-startup`** keeps your saved preferences and third-party add-ons out of the result, so the same conversion produces the same file on any machine.
+2. **The runner writes its payload to a file, never to stdout.** Blender prints progress, add-on chatter and render statistics on stdout; picking a payload out of that stream is guesswork. A missing result file is therefore an unambiguous "Blender died", and the error carries the log tail that says why.
+3. **One process per call.** A crashed job cannot corrupt the next one, and no state leaks between calls.
+
+Every operator is resolved by name with fallbacks and every keyword is filtered against the operator's own RNA before the call, so the importer and exporter renames between Blender 3.x and 4.x do not break a tool.
+
+## Errors
+
+Failures come back as structured tool errors, each naming a fix:
+
+| Code | Meaning |
+|---|---|
+| `blender_not_found` | No Blender on `PATH` or at the standard locations. Install it, or set `BLENDER_PATH`. |
+| `blender_too_old` | Found a Blender older than 3.0. |
+| `input_not_found` | The path does not exist or is unreadable. |
+| `format_unsupported` | This build has no importer or exporter for that extension. The message lists the ones it does have. |
+| `engine_unavailable` | The requested render engine is not in this build. |
+| `timeout` | The job passed `BLENDER_MCP_TIMEOUT_MS` and was killed. |
+| `blender_crashed` | Blender exited without writing a result. The error carries its log tail. |
+
+---
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `BLENDER_PATH` | discovered | Absolute path to the Blender executable. |
+| `BLENDER_MCP_TIMEOUT_MS` | `300000` | Ceiling for one Blender job. |
+| `BLENDER_MCP_WORKDIR` | `<tmpdir>/three-ws-blender-mcp` | Where outputs land with no explicit output path. |
+| `BLENDER_MCP_ALLOW_PYTHON` | `1` | `0` withdraws `blender_run_python` from the tool list entirely. |
+| `THREE_WS_BASE` | `https://three.ws` | Deployment backing `blender_forge_import`. |
+| `THREE_WS_FORGE_TIMEOUT_MS` | `600000` | Ceiling for one generation. |
+| `THREE_WS_FORGE_PROVIDER_KEY` | unset | Meshy/Tripo key for the bring-your-own-key geometry lane. |
+
+## Security
+
+`blender_run_python` executes caller-supplied Python inside Blender with this server's permissions, including filesystem access. That is what the tool is for, and it is annotated `destructiveHint: true` so a client prompts before running it. For unattended or shared deployments set `BLENDER_MCP_ALLOW_PYTHON=0`: the tool is then never advertised, and the other five keep working.
+
+Only `blender_forge_import` reaches the network, and only the deployment named by `THREE_WS_BASE`. Everything else stays on the machine. The broader model is in [MCP safety](./mcp-safety.md).
+
+---
+
+## Related
+
+- [`integrations/blender/`](https://github.com/nirholas/three.ws/tree/main/integrations/blender) is the artist-facing counterpart: a Blender add-on with a sidebar panel that generates three.ws models from inside the GUI. This server is the agent-facing one; they can be installed side by side.
+- [MCP integration](./mcp.md) lists every three.ws MCP server.
+- [3D API](./3d-api.md) documents the Forge endpoints behind `blender_forge_import`.
+- [Scenes MCP](https://www.npmjs.com/package/@three-ws/scene-mcp) composes whole 3D worlds from one sentence.
diff --git a/docs/mcp.md b/docs/mcp.md
index 2663604cd..50ef2409d 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -43,7 +43,7 @@ The MCP server configuration is at `.mcp.json` in the project root, which Claude
## The full three.ws MCP ecosystem
-This page documents the hosted avatar/3D server at `/api/mcp`, but it's one of **50 three.ws MCP servers**, all listed in the [official MCP registry](https://registry.modelcontextprotocol.io/?q=io.github.nirholas), so any MCP-compatible client can discover them by name.
+This page documents the hosted avatar/3D server at `/api/mcp`, but it's one of **51 three.ws MCP servers**, all listed in the [official MCP registry](https://registry.modelcontextprotocol.io/?q=io.github.nirholas), so any MCP-compatible client can discover them by name.
The hosted servers are also self-describing: [`https://three.ws/.well-known/mcp.json`](https://three.ws/.well-known/mcp.json) is a machine-readable directory of every hosted endpoint with its transport, auth model, and a one-line description, so an agent can enumerate all of them with a single fetch.
@@ -61,7 +61,7 @@ There are two kinds. **Hosted remote servers** run over Streamable HTTP with not
| pump.fun | `/api/pump-fun-mcp` | Free pump.fun + Solana token tools; `get_new_tokens` and `get_trending_tokens` read the live pump.fun feed with no indexer needed; `pumpfun_upload_metadata` needs a key |
| IBM x402 | `/api/ibm-mcp` | Pay-per-use IBM Granite AI |
-**Forty install-and-run servers** on npm under the `@three-ws` scope, each running over stdio with one command:
+**Forty-one install-and-run servers** on npm under the `@three-ws` scope, each running over stdio with one command:
```bash
# 3D & avatars
@@ -71,6 +71,7 @@ npx -y @three-ws/avatar-mcp # drop a live 3D avatar into any chat
npx -y @three-ws/concierge-mcp # ask any site's AI concierge; generate the 3D chat-widget embed
npx -y @three-ws/avatar-agent # turn any GLB into a riggable 3D AI agent
npx -y @three-ws/mcp-server # full 3D + agent toolkit, paid per call in USDC
+npx -y @three-ws/blender-mcp # drive the Blender on your own machine, headless (needs Blender 3.0+ installed)
# Payments & the agent economy
npx -y @three-ws/x402-mcp # self-custodial wallet: find, inspect & pay any x402 service in USDC
@@ -149,6 +150,7 @@ Ready-to-submit listing packages for each directory, plus the canonical metadata
Deep dives — every tool, argument, env var, and example:
- **Hosted remote:** [3D Studio (free)](./mcp-studio.md) · [3D Studio (paid)](./mcp-3d-studio.md) · [Agent wallet](./mcp-agent.md) · [x402 Bazaar](./mcp-x402-bazaar.md) · [IBM x402](./ibm-x402-mcp.md)
+- **Runs against your machine:** [Blender MCP](./blender-mcp.md) drives the Blender installed on your own computer, headless: inspect, convert, render and script 3D files, plus text-to-3D straight into a scene.
- **Install-and-run:** each npm server ships its usage guide (tools, arguments, env vars, examples) in its package README on [npmjs.com/org/three-ws](https://www.npmjs.com/org/three-ws). The [MCP Tools Catalog](./mcp-tools.md) maps every tool to its server and price.
---
diff --git a/integrations/README.md b/integrations/README.md
index c69035893..ea1306717 100644
--- a/integrations/README.md
+++ b/integrations/README.md
@@ -9,6 +9,13 @@ generated without leaving the DCC.
| Blender add-on | [`blender/three_ws/`](blender/three_ws/) | Blender 4.0+ |
| ComfyUI nodes | [`comfyui/three_ws_nodes/`](comfyui/three_ws_nodes/) | ComfyUI |
+Driving Blender from an **agent** rather than by hand is a different job, and it
+has its own package: [`packages/blender-mcp/`](../packages/blender-mcp) is an MCP
+server that runs Blender headlessly (no GUI, no add-on) so an assistant can
+inspect, convert, render, and script 3D files, and pull a Forge generation
+straight into a scene. The add-on below is the artist-facing surface; the two
+install side by side.
+
Both speak to the same auth-free endpoints:
- `POST /api/forge` — text→3D and image→3D
diff --git a/package-lock.json b/package-lock.json
index 91928d7fd..4cad8212f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -72,7 +72,8 @@
"packages/portal",
"packages/tty-avatar",
"packages/home-bridge",
- "packages/home-mcp"
+ "packages/home-mcp",
+ "packages/blender-mcp"
],
"dependencies": {
"@0xsplits/splits-sdk": "^6.5.0",
@@ -16680,6 +16681,10 @@
"resolved": "packages/billing-mcp",
"link": true
},
+ "node_modules/@three-ws/blender-mcp": {
+ "resolved": "packages/blender-mcp",
+ "link": true
+ },
"node_modules/@three-ws/brain-mcp": {
"resolved": "packages/brain-mcp",
"link": true
@@ -40274,6 +40279,21 @@
"node": ">=20"
}
},
+ "packages/blender-mcp": {
+ "name": "@three-ws/blender-mcp",
+ "version": "0.1.0",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "@modelcontextprotocol/sdk": "^1.29.0",
+ "zod": "^3.23.8"
+ },
+ "bin": {
+ "blender-mcp": "src/index.js"
+ },
+ "engines": {
+ "node": ">=20"
+ }
+ },
"packages/brain-mcp": {
"name": "@three-ws/brain-mcp",
"version": "0.1.3",
diff --git a/package.json b/package.json
index 9a0cf069f..b8833eb0e 100644
--- a/package.json
+++ b/package.json
@@ -128,7 +128,8 @@
"packages/portal",
"packages/tty-avatar",
"packages/home-bridge",
- "packages/home-mcp"
+ "packages/home-mcp",
+ "packages/blender-mcp"
],
"main": "src/app.js",
"browserslist": [
diff --git a/packages/blender-mcp/LICENSE b/packages/blender-mcp/LICENSE
new file mode 100644
index 000000000..b5ae2a4e1
--- /dev/null
+++ b/packages/blender-mcp/LICENSE
@@ -0,0 +1,201 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2026 nirholas
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/packages/blender-mcp/README.md b/packages/blender-mcp/README.md
new file mode 100644
index 000000000..3b42c2c91
--- /dev/null
+++ b/packages/blender-mcp/README.md
@@ -0,0 +1,160 @@
+<p align="center">
+ <a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a>
+</p>
+
+<h1 align="center">@three-ws/blender-mcp</h1>
+
+<p align="center"><strong>Give any AI agent the Blender on your machine. Headless, no GUI, no add-on to install.</strong></p>
+
+<p align="center">
+ <img alt="license" src="https://img.shields.io/npm/l/@three-ws/blender-mcp?color=3b82f6">
+ <img alt="node" src="https://img.shields.io/node/v/@three-ws/blender-mcp?color=339933&logo=node.js">
+ <img alt="blender" src="https://img.shields.io/badge/Blender-3.0%2B-ea7600?logo=blender&logoColor=white">
+ <a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
+</p>
+
+---
+
+> A [Model Context Protocol](https://modelcontextprotocol.io) server that hands an AI assistant a real Blender over stdio. Inspect a 3D file, convert between GLB, glTF, FBX, OBJ, STL, PLY, Collada, Alembic, USD and `.blend`, render an auto-framed and auto-lit preview PNG, run a `bpy` script against a scene, and generate a model from a text prompt on the free three.ws Forge lane.
+
+Blender runs in background mode (`blender -b`), one process per call. That means it works on a server, in CI, and inside a container with no display, no GUI session to keep alive, and no add-on to install into Blender first. Everything is real: each tool drives the Blender installed on the machine, and `blender_forge_import` calls the live public three.ws generation pipeline.
+
+## Requirements
+
+- **Node.js 20+**
+- **Blender 3.0 or newer**, installed locally. [Download](https://www.blender.org/download/) it, or install it from your package manager. If it is not on `PATH`, set `BLENDER_PATH` to the executable (`/Applications/Blender.app/Contents/MacOS/Blender` on macOS).
+
+Call `blender_info` first if anything misbehaves: it reports the exact executable, version, render engines, and file formats this build supports.
+
+## Install
+
+```bash
+npm install @three-ws/blender-mcp
+```
+
+Or run it with `npx` (no install):
+
+```bash
+npx -y @three-ws/blender-mcp
+```
+
+### Claude Code
+
+```bash
+claude mcp add blender -- npx -y @three-ws/blender-mcp
+```
+
+### Claude Desktop / Cursor
+
+Paste this into your MCP config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+ "mcpServers": {
+ "blender": {
+ "command": "npx",
+ "args": ["-y", "@three-ws/blender-mcp"]
+ }
+ }
+}
+```
+
+Add `"env": { "BLENDER_PATH": "/path/to/blender" }` if Blender is not on `PATH`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `blender_info` | Reports the Blender being driven: path, version, bundled Python, usable render engines, and the import/export formats this build actually supports. Read-only. |
+| `blender_scene_info` | Opens a 3D file and describes it: objects with types, parents, dimensions and modifiers; evaluated triangle and vertex counts; materials; armature bone names; animation actions with frame ranges; world-space bounds. Read-only. |
+| `blender_convert` | Imports one format and exports another, chosen by the file extensions. Applies modifiers by default and can bake in a uniform unit scale. The exact format list depends on the build (some Linux packages ship without USD, Collada, or Alembic), and `blender_info` reports what yours actually has. |
+| `blender_render` | Renders a still PNG. If the file has no camera, one is created and framed to the model's bounding sphere; if it has no light, a key light and a lit world are added. A scene that already has its own camera and lighting renders as authored. |
+| `blender_run_python` | Runs a `bpy` script against a scene, optionally opening a file first and exporting the result afterwards. The escape hatch for anything the other tools do not cover. |
+| `blender_forge_import` | Generates a model from a text prompt on the public three.ws Forge pipeline and brings it into Blender, converting on the way in if the output asks for another format. The default image lane is free. |
+
+### Examples
+
+Describe a file before touching it:
+
+```
+> What is in ~/assets/character.fbx?
+
+blender_scene_info { "input": "~/assets/character.fbx" }
+→ 4 meshes, 41,208 triangles, 1 armature (67 bones), 3 actions, bounds 1.78m tall
+```
+
+Convert a client's FBX into a web-ready GLB, in metres:
+
+```
+blender_convert { "input": "character.fbx", "output": "character.glb", "scale": 0.01 }
+```
+
+See what you just made:
+
+```
+blender_render { "input": "character.glb", "output": "preview.png", "samples": 64 }
+```
+
+Halve the triangle count and export in one call:
+
+```
+blender_run_python {
+ "input": "character.glb",
+ "output": "character-lod1.glb",
+ "code": "import bpy\nfor obj in bpy.data.objects:\n if obj.type == 'MESH':\n obj.modifiers.new('Decimate', 'DECIMATE').ratio = 0.5\nresult = {'meshes': len([o for o in bpy.data.objects if o.type == 'MESH'])}"
+}
+```
+
+Generate an asset and open it as a `.blend`:
+
+```
+blender_forge_import { "prompt": "a weathered brass diving helmet", "output": "helmet.blend" }
+```
+
+## How a call works
+
+Every tool call spawns `blender -b --factory-startup --python src/py/runner.py -- <job.json> <result.json>` and exits. Three consequences worth knowing:
+
+- **`--factory-startup`** keeps your saved preferences and third-party add-ons out of the result, so a conversion produces the same file on any machine.
+- **The runner writes its payload to a file, never to stdout.** Blender prints progress, add-on chatter, and render statistics on stdout, and picking a payload out of that stream is guesswork. A missing result file therefore means Blender died, and the error carries the log tail that says why.
+- **One process per call.** A crashed job cannot corrupt the next one, and nothing stays resident between calls.
+
+Failures come back as structured tool errors (`input_not_found`, `format_unsupported`, `engine_unavailable`, `timeout`, `blender_not_found`, `blender_crashed`), each with a message that says what to do about it.
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `BLENDER_PATH` | discovered on `PATH` and at the platform's standard install locations | Absolute path to the Blender executable. |
+| `BLENDER_MCP_TIMEOUT_MS` | `300000` | Ceiling for one Blender job. |
+| `BLENDER_MCP_WORKDIR` | `<tmpdir>/three-ws-blender-mcp` | Where outputs land when a tool is called without an explicit output path. |
+| `BLENDER_MCP_ALLOW_PYTHON` | `1` | Set to `0` to withdraw `blender_run_python` from the advertised tool list entirely. |
+| `THREE_WS_BASE` | `https://three.ws` | Deployment backing `blender_forge_import`. |
+| `THREE_WS_FORGE_TIMEOUT_MS` | `600000` | Ceiling for one text-to-3D generation. |
+| `THREE_WS_FORGE_PROVIDER_KEY` | unset | Meshy/Tripo key for the bring-your-own-key geometry lane. The default image lane is free and needs no key. |
+
+## Security
+
+`blender_run_python` executes caller-supplied Python inside Blender with the permissions of this server: it can read and write the local filesystem. That is the point of the tool, and it is annotated `destructiveHint: true` so a client can prompt before running it. For unattended or shared deployments, set `BLENDER_MCP_ALLOW_PYTHON=0` and the tool is never advertised.
+
+Everything else stays local. Only `blender_forge_import` reaches the network, and only to the three.ws deployment named by `THREE_WS_BASE`.
+
+## Development
+
+```bash
+node src/index.js # run the server over stdio
+npm test # offline invariants + real-Blender integration
+npm run inspect # open the MCP Inspector against it
+```
+
+`test/registration.test.mjs` runs offline and passes with no Blender installed. `test/blender-session.test.mjs` drives the server through a real MCP stdio session against the local Blender, building its fixture with Blender itself; it skips cleanly when no Blender is present.
+
+## Related
+
+- [`integrations/blender/`](../../integrations/blender) is the artist-facing counterpart: a Blender add-on with a sidebar panel that generates three.ws models from inside the GUI. This package is the agent-facing one.
+- [`@three-ws/scene-mcp`](../scene-mcp) composes whole 3D worlds from a sentence.
+- [three.ws](https://three.ws) is the platform behind the Forge pipeline.
+
+## License
+
+Apache-2.0
diff --git a/packages/blender-mcp/package.json b/packages/blender-mcp/package.json
new file mode 100644
index 000000000..742d113f2
--- /dev/null
+++ b/packages/blender-mcp/package.json
@@ -0,0 +1,61 @@
+{
+ "name": "@three-ws/blender-mcp",
+ "version": "0.1.0",
+ "mcpName": "io.github.nirholas/blender-mcp",
+ "description": "Drive the Blender on your machine from any AI agent, headless. Inspect a 3D file, convert between GLB/glTF/FBX/OBJ/STL/PLY/DAE/USD/Alembic/.blend, render an auto-framed and auto-lit preview PNG, run a bpy script against a scene, and generate a model from a text prompt on the free three.ws Forge lane. No GUI, no add-on to install, no key.",
+ "type": "module",
+ "author": "nirholas <[email protected]>",
+ "license": "Apache-2.0",
+ "homepage": "https://three.ws",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/nirholas/three.ws.git",
+ "directory": "packages/blender-mcp"
+ },
+ "bugs": {
+ "url": "https://github.com/nirholas/three.ws/issues"
+ },
+ "keywords": [
+ "mcp",
+ "model-context-protocol",
+ "blender",
+ "bpy",
+ "three.ws",
+ "3d",
+ "glb",
+ "gltf",
+ "fbx",
+ "usd",
+ "render",
+ "headless",
+ "ai-agent"
+ ],
+ "publishConfig": {
+ "access": "public"
+ },
+ "files": [
+ "src",
+ "server.json",
+ "README.md",
+ "LICENSE"
+ ],
+ "bin": {
+ "blender-mcp": "src/index.js"
+ },
+ "main": "./src/index.js",
+ "exports": {
+ ".": "./src/index.js"
+ },
+ "engines": {
+ "node": ">=20"
+ },
+ "scripts": {
+ "start": "node src/index.js",
+ "test": "node --test \"test/**/*.test.mjs\"",
+ "inspect": "npx -y @modelcontextprotocol/inspector node src/index.js"
+ },
+ "dependencies": {
+ "@modelcontextprotocol/sdk": "^1.29.0",
+ "zod": "^3.23.8"
+ }
+}
diff --git a/packages/blender-mcp/server.json b/packages/blender-mcp/server.json
new file mode 100644
index 000000000..2994f519d
--- /dev/null
+++ b/packages/blender-mcp/server.json
@@ -0,0 +1,82 @@
+{
+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+ "name": "io.github.nirholas/blender-mcp",
+ "title": "three.ws Blender",
+ "description": "Drive a local Blender headlessly: inspect, convert, render and script 3D files.",
+ "websiteUrl": "https://three.ws",
+ "icons": [
+ {
+ "src": "https://three.ws/three-ws-mcp-icon.svg",
+ "mimeType": "image/svg+xml",
+ "sizes": [
+ "any"
+ ]
+ }
+ ],
+ "repository": {
+ "url": "https://github.com/nirholas/three.ws",
+ "source": "github",
+ "subfolder": "packages/blender-mcp"
+ },
+ "version": "0.1.0",
+ "packages": [
+ {
+ "registryType": "npm",
+ "identifier": "@three-ws/blender-mcp",
+ "version": "0.1.0",
+ "runtimeHint": "npx",
+ "transport": {
+ "type": "stdio"
+ },
+ "environmentVariables": [
+ {
+ "name": "BLENDER_PATH",
+ "description": "Absolute path to the Blender 3.0+ executable. Leave unset to discover it on PATH and at the platform's standard install locations.",
+ "format": "string",
+ "isRequired": false
+ },
+ {
+ "name": "BLENDER_MCP_TIMEOUT_MS",
+ "description": "Ceiling for one Blender job in milliseconds. Renders and heavy conversions are the slow ones.",
+ "format": "number",
+ "isRequired": false,
+ "default": "300000"
+ },
+ {
+ "name": "BLENDER_MCP_WORKDIR",
+ "description": "Directory for outputs written when a tool is called without an explicit output path.",
+ "format": "string",
+ "isRequired": false
+ },
+ {
+ "name": "BLENDER_MCP_ALLOW_PYTHON",
+ "description": "Set to 0 to withdraw blender_run_python, which executes caller-supplied Python inside Blender, from the advertised tool list.",
+ "format": "string",
+ "isRequired": false,
+ "default": "1"
+ },
+ {
+ "name": "THREE_WS_BASE",
+ "description": "Base URL of the three.ws deployment backing blender_forge_import.",
+ "format": "string",
+ "isRequired": false,
+ "default": "https://three.ws"
+ },
+ {
+ "name": "THREE_WS_FORGE_TIMEOUT_MS",
+ "description": "Ceiling for one text-to-3D generation in milliseconds.",
+ "format": "number",
+ "isRequired": false,
+ "default": "600000"
+ },
+ {
+ "name": "THREE_WS_FORGE_PROVIDER_KEY",
+ "description": "Meshy/Tripo API key for the bring-your-own-key geometry lane. The default image lane is free and needs no key.",
+ "format": "string",
+ "isSecret": true,
+ "isRequired": false
+ }
+ ]
+ }
+ ]
+}
diff --git a/packages/blender-mcp/smithery.yaml b/packages/blender-mcp/smithery.yaml
new file mode 100644
index 000000000..f8ebf1eb8
--- /dev/null
+++ b/packages/blender-mcp/smithery.yaml
@@ -0,0 +1,21 @@
+# Smithery deployment config for @three-ws/blender-mcp
+# https://smithery.ai/docs/config#smitheryyaml
+#
+# This server drives a Blender install on the host it runs on, so a hosted
+# deployment needs Blender 3.0+ present in the runtime image.
+startCommand:
+ type: stdio
+ configSchema:
+ type: object
+ properties:
+ blenderPath:
+ type: string
+ title: Blender executable
+ description: Absolute path to Blender 3.0+. Leave empty to discover it on PATH.
+ required: []
+ commandFunction: |
+ (config) => ({
+ command: "npx",
+ args: ["-y", "@three-ws/blender-mcp"],
+ env: config.blenderPath ? { BLENDER_PATH: config.blenderPath } : {}
+ })
diff --git a/packages/blender-mcp/src/config.js b/packages/blender-mcp/src/config.js
new file mode 100644
index 000000000..c812893f6
--- /dev/null
+++ b/packages/blender-mcp/src/config.js
@@ -0,0 +1,60 @@
+// Centralized env for the Blender MCP.
+//
+// This server drives a LOCAL Blender install in background mode. It holds no
+// secret and signs nothing: the only knobs are which Blender to run, how long
+// to let a job run, where scratch files go, and which three.ws deployment the
+// forge bridge talks to.
+
+import os from 'node:os';
+import path from 'node:path';
+
+export function env(key, fallback) {
+ const value = process.env[key];
+ return value !== undefined && String(value).trim() !== '' ? String(value).trim() : fallback;
+}
+
+function positiveNumber(key, fallback) {
+ const raw = env(key);
+ if (raw === undefined) return fallback;
+ const n = Number(raw);
+ if (!Number.isFinite(n) || n <= 0) {
+ throw Object.assign(new Error(`${key} must be a positive number (got "${raw}")`), { code: 'bad_config' });
+ }
+ return n;
+}
+
+function boolean(key, fallback) {
+ const raw = env(key);
+ if (raw === undefined) return fallback;
+ return !['0', 'false', 'no', 'off'].includes(raw.toLowerCase());
+}
+
+// Absolute path to the Blender executable. Left unset, the binary is discovered
+// on PATH and at the standard install locations for the host platform.
+export const BLENDER_PATH = env('BLENDER_PATH');
+
+// Ceiling for one Blender job. Renders and heavy conversions are the slow ones;
+// everything else finishes in seconds.
+export const JOB_TIMEOUT_MS = positiveNumber('BLENDER_MCP_TIMEOUT_MS', 300000);
+
+// Where generated files land when a tool is called without an explicit output
+// path, and where per-job scratch directories are created.
+export const WORKDIR = path.resolve(env('BLENDER_MCP_WORKDIR', path.join(os.tmpdir(), 'three-ws-blender-mcp')));
+
+// blender_run_python executes caller-supplied Python inside Blender with full
+// filesystem access. It is registered by default because scripted scene edits
+// are the point of driving Blender from an agent; set this to 0 in shared or
+// unattended deployments and the tool is not advertised at all.
+export const ALLOW_PYTHON = boolean('BLENDER_MCP_ALLOW_PYTHON', true);
+
+// three.ws deployment backing blender_forge_import.
+export const THREE_WS_BASE = env('THREE_WS_BASE', 'https://three.ws').replace(/\/+$/, '');
+
+// Ceiling for one text-to-3D generation, which runs on a shared GPU lane.
+export const FORGE_TIMEOUT_MS = positiveNumber('THREE_WS_FORGE_TIMEOUT_MS', 600000);
+
+// Optional Meshy/Tripo key for the BYOK geometry lane. The default image lane
+// (FLUX to TRELLIS) is free and needs no key.
+export const FORGE_PROVIDER_KEY = env('THREE_WS_FORGE_PROVIDER_KEY');
+
+export const USER_AGENT = '@three-ws/blender-mcp';
diff --git a/packages/blender-mcp/src/index.js b/packages/blender-mcp/src/index.js
new file mode 100644
index 000000000..b2c5e3350
--- /dev/null
+++ b/packages/blender-mcp/src/index.js
@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// @three-ws/blender-mcp: MCP server entry point.
+//
+// Gives any AI assistant a local Blender over stdio:
+// • blender_info: what this Blender build is and can do
+// • blender_scene_info: read a 3D file and describe what is inside it
+// • blender_convert: import one format, export another
+// • blender_render: render a still preview, auto-framed and auto-lit
+// • blender_run_python: run a bpy script against a scene
+// • blender_forge_import: three.ws text-to-3D, brought into Blender
+//
+// Blender runs headless (`blender -b`), one process per call, so this works on
+// a server, in CI, and in a container. Nothing is mocked: every tool drives the
+// real Blender on this machine, and blender_forge_import calls the live public
+// three.ws Forge pipeline.
+//
+// Run standalone:
+// node packages/blender-mcp/src/index.js
+//
+// Or wire into Claude Code / Cursor (see README.md).
+
+import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { ALLOW_PYTHON } from './config.js';
+import { def as blenderInfo } from './tools/info.js';
+import { def as sceneInfo } from './tools/scene-info.js';
+import { def as convert } from './tools/convert.js';
+import { def as render } from './tools/render.js';
+import { def as runPython } from './tools/run-python.js';
+import { def as forgeImport } from './tools/forge-import.js';
+
+// Single source of truth for the advertised server version: package.json.
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require('../package.json');
+
+// blender_run_python executes caller-supplied code. It is advertised by default
+// because scripted scene edits are most of what an agent needs Blender for, and
+// withdrawn entirely when BLENDER_MCP_ALLOW_PYTHON=0.
+export const TOOLS = [blenderInfo, sceneInfo, convert, render, forgeImport, ...(ALLOW_PYTHON ? [runPython] : [])];
+
+/**
+ * Construct a fully-registered McpServer without connecting a transport.
+ * Registration touches neither Blender nor the network, so this is safe to
+ * import from tests.
+ * @returns {McpServer}
+ */
+export function buildServer() {
+ const server = new McpServer(
+ { name: 'blender-mcp', title: 'three.ws Blender', version: PKG_VERSION },
+ {
+ capabilities: { tools: {} },
+ instructions:
+ 'three.ws Blender MCP: drive the Blender install on THIS machine, headless. blender_info reports the ' +
+ 'executable, version, render engines, and supported formats, and is the right first call when anything ' +
+ 'fails. blender_scene_info opens a 3D file and describes it (objects, evaluated triangle counts, ' +
+ 'materials, armature bones, animations, world bounds). blender_convert bridges formats in both ' +
+ 'directions (.glb .gltf .fbx .obj .stl .ply .dae .abc .usd .x3d .blend), applying modifiers and an ' +
+ 'optional unit scale. blender_render produces a still PNG, adding a framed camera and a key light when ' +
+ 'the file has none, so a bare asset previews with no setup. blender_run_python runs a bpy script for ' +
+ 'edits the other tools do not cover and can export the result in the same call. blender_forge_import ' +
+ 'generates a model from a text prompt on the free public three.ws Forge lane and brings it in. Blender ' +
+ 'must be installed locally (3.0+); set BLENDER_PATH if it is not on PATH.',
+ },
+ );
+
+ for (const tool of TOOLS) {
+ server.registerTool(
+ tool.name,
+ {
+ title: tool.title,
+ description: tool.description,
+ inputSchema: tool.inputSchema,
+ annotations: tool.annotations,
+ },
+ async (args, extra) => {
+ try {
+ const result = await tool.handler(args, extra);
+ const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+ return { content: [{ type: 'text', text }] };
+ } catch (err) {
+ const payload = {
+ ok: false,
+ error: err?.code || 'unhandled',
+ message: err?.message || String(err),
+ ...(err?.status ? { status: err.status } : {}),
+ ...(err?.traceback ? { traceback: err.traceback } : {}),
+ ...(err?.log ? { blender_log: err.log } : {}),
+ };
+ return {
+ content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+ isError: true,
+ };
+ }
+ },
+ );
+ }
+
+ return server;
+}
+
+async function main() {
+ const server = buildServer();
+ const transport = new StdioServerTransport();
+ await server.connect(transport);
+ console.error(`[blender-mcp@${PKG_VERSION}] connected over stdio with ${TOOLS.length} tools`);
+}
+
+// Connect stdio ONLY when this file is the process entry point. Importing the
+// module (tests, embedding) must not grab the transport. realpath both sides:
+// npm bin shims are symlinks, so argv[1] may differ from import.meta.url.
+function isProcessEntryPoint() {
+ if (!process.argv[1]) return false;
+ try {
+ return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+ } catch {
+ return false;
+ }
+}
+
+if (isProcessEntryPoint()) {
+ main().catch((err) => {
+ console.error('[blender-mcp] fatal:', err);
+ process.exit(1);
+ });
+}
diff --git a/packages/blender-mcp/src/lib/blender.js b/packages/blender-mcp/src/lib/blender.js
new file mode 100644
index 000000000..98dde63a9
--- /dev/null
+++ b/packages/blender-mcp/src/lib/blender.js
@@ -0,0 +1,229 @@
+// Locate and drive a local Blender install in background mode.
+//
+// Every tool call is one `blender -b --factory-startup --python runner.py`
+// process. That is deliberate: a crashed job cannot corrupt the next one, and
+// nothing has to stay resident between calls. --factory-startup keeps a user's
+// saved preferences and third-party add-ons out of the result, so a conversion
+// is reproducible on any machine.
+//
+// The runner writes its payload to a result FILE, never to stdout, because
+// Blender prints progress, add-on chatter, and render statistics on stdout and
+// picking a payload out of that stream is guesswork. A missing result file is
+// therefore an unambiguous signal that Blender died, and the log tail says why.
+
+import { spawn } from 'node:child_process';
+import { access, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { BLENDER_PATH, JOB_TIMEOUT_MS, WORKDIR } from '../config.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const RUNNER_PATH = path.join(HERE, '..', 'py', 'runner.py');
+
+// Blender 3.0 is the floor: it is the first release with the operator surface
+// the runner relies on, and matches what the glTF add-on supports.
+const MIN_VERSION = [3, 0];
+
+const LOG_TAIL_BYTES = 4000;
+
+let cached = null;
+
+function candidatePaths() {
+ const found = [];
+ if (BLENDER_PATH) found.push(BLENDER_PATH);
+
+ const exe = process.platform === 'win32' ? 'blender.exe' : 'blender';
+ for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+ if (dir) found.push(path.join(dir, exe));
+ }
+
+ if (process.platform === 'darwin') {
+ found.push('/Applications/Blender.app/Contents/MacOS/Blender');
+ found.push(path.join(os.homedir(), 'Applications/Blender.app/Contents/MacOS/Blender'));
+ } else if (process.platform === 'win32') {
+ for (const root of ['C:\\Program Files\\Blender Foundation', 'C:\\Program Files (x86)\\Blender Foundation']) {
+ for (const version of ['4.5', '4.4', '4.3', '4.2', '4.1', '4.0', '3.6']) {
+ found.push(path.join(root, `Blender ${version}`, 'blender.exe'));
+ }
+ }
+ } else {
+ found.push('/usr/bin/blender', '/usr/local/bin/blender', '/snap/bin/blender', '/opt/blender/blender');
+ }
+ return found;
+}
+
+function runVersion(binary) {
+ return new Promise((resolve) => {
+ let child;
+ try {
+ child = spawn(binary, ['--version'], { stdio: ['ignore', 'pipe', 'pipe'] });
+ } catch {
+ resolve(null);
+ return;
+ }
+ let out = '';
+ const timer = setTimeout(() => child.kill('SIGKILL'), 20000);
+ child.stdout.on('data', (chunk) => {
+ out += chunk;
+ });
+ child.on('error', () => {
+ clearTimeout(timer);
+ resolve(null);
+ });
+ child.on('close', () => {
+ clearTimeout(timer);
+ const match = /Blender\s+(\d+)\.(\d+)(?:\.(\d+))?/i.exec(out);
+ if (!match) {
+ resolve(null);
+ return;
+ }
+ resolve({
+ version: `${match[1]}.${match[2]}${match[3] ? `.${match[3]}` : ''}`,
+ tuple: [Number(match[1]), Number(match[2]), Number(match[3] || 0)],
+ });
+ });
+ });
+}
+
+/**
+ * Find a usable Blender executable, once per process.
+ *
+ * @returns {Promise<{path: string, version: string, tuple: number[]}>}
+ * @throws {Error} code 'blender_not_found' or 'blender_too_old', with an actionable message.
+ */
+export async function resolveBlender() {
+ if (cached) return cached;
+
+ const tried = [];
+ for (const candidate of candidatePaths()) {
+ if (tried.includes(candidate)) continue;
+ tried.push(candidate);
+ try {
+ await access(candidate, constants.X_OK);
+ } catch {
+ continue;
+ }
+ const info = await runVersion(candidate);
+ if (!info) continue;
+ if (info.tuple[0] < MIN_VERSION[0] || (info.tuple[0] === MIN_VERSION[0] && info.tuple[1] < MIN_VERSION[1])) {
+ throw Object.assign(
+ new Error(
+ `Blender ${info.version} at ${candidate} is too old. This server needs ${MIN_VERSION.join('.')} or newer.`,
+ ),
+ { code: 'blender_too_old' },
+ );
+ }
+ cached = { path: candidate, version: info.version, tuple: info.tuple };
+ return cached;
+ }
+
+ throw Object.assign(
+ new Error(
+ 'No Blender executable found. Install Blender 3.0 or newer from https://www.blender.org/download/ ' +
+ 'and either put it on PATH or set BLENDER_PATH to the executable ' +
+ '(macOS: /Applications/Blender.app/Contents/MacOS/Blender).',
+ ),
+ { code: 'blender_not_found', tried: tried.slice(0, 12) },
+ );
+}
+
+/** Reset the cached executable. Tests use this; nothing else needs it. */
+export function resetBlenderCache() {
+ cached = null;
+}
+
+function tail(text) {
+ const trimmed = String(text || '');
+ return trimmed.length > LOG_TAIL_BYTES ? trimmed.slice(-LOG_TAIL_BYTES) : trimmed;
+}
+
+/** Create the shared workdir on demand and return it. */
+export async function ensureWorkdir() {
+ await mkdir(WORKDIR, { recursive: true });
+ return WORKDIR;
+}
+
+/**
+ * Run one job through the in-Blender runner and return its payload.
+ *
+ * @param {object} job `{ op, ... }`, matching src/py/runner.py.
+ * @param {{ timeoutMs?: number }} [opts]
+ * @returns {Promise<object>} The runner payload (always `ok: true` on return).
+ * @throws {Error} with `.code` ('timeout' | 'blender_crashed' | the runner's own code)
+ * and, when Blender produced diagnostics, `.log`.
+ */
+export async function runJob(job, { timeoutMs } = {}) {
+ const blender = await resolveBlender();
+ await ensureWorkdir();
+ const dir = await mkdtemp(path.join(WORKDIR, 'job-'));
+ const jobPath = path.join(dir, 'job.json');
+ const resultPath = path.join(dir, 'result.json');
+ const limit = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : JOB_TIMEOUT_MS;
+
+ try {
+ await writeFile(jobPath, JSON.stringify(job), 'utf8');
+
+ const args = ['-b', '--factory-startup', '-noaudio', '--python', RUNNER_PATH, '--', jobPath, resultPath];
+ const outcome = await new Promise((resolve, reject) => {
+ const child = spawn(blender.path, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+ let stdout = '';
+ let stderr = '';
+ let timedOut = false;
+ const timer = setTimeout(() => {
+ timedOut = true;
+ child.kill('SIGKILL');
+ }, limit);
+
+ child.stdout.on('data', (chunk) => {
+ stdout = tail(stdout + chunk);
+ });
+ child.stderr.on('data', (chunk) => {
+ stderr = tail(stderr + chunk);
+ });
+ child.on('error', (err) => {
+ clearTimeout(timer);
+ reject(Object.assign(new Error(`Could not start Blender: ${err.message}`), { code: 'blender_spawn_failed' }));
+ });
+ child.on('close', (code, signal) => {
+ clearTimeout(timer);
+ if (timedOut) {
+ reject(
+ Object.assign(new Error(`Blender job "${job.op}" exceeded ${limit}ms and was killed.`), {
+ code: 'timeout',
+ log: tail(`${stdout}\n${stderr}`),
+ }),
+ );
+ return;
+ }
+ resolve({ code, signal, log: tail(`${stdout}\n${stderr}`) });
+ });
+ });
+
+ let payload;
+ try {
+ payload = JSON.parse(await readFile(resultPath, 'utf8'));
+ } catch {
+ throw Object.assign(
+ new Error(
+ `Blender exited ${outcome.signal ? `on ${outcome.signal}` : `with code ${outcome.code}`} without writing a result. ` +
+ 'The log tail below is what it printed before dying.',
+ ),
+ { code: 'blender_crashed', log: outcome.log },
+ );
+ }
+
+ if (payload.ok === false) {
+ throw Object.assign(new Error(payload.message || 'The Blender job failed.'), {
+ code: payload.error || 'blender_error',
+ ...(payload.traceback ? { traceback: payload.traceback } : {}),
+ log: outcome.log,
+ });
+ }
+ return { ...payload, blender_path: blender.path };
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+}
diff --git a/packages/blender-mcp/src/lib/forge.js b/packages/blender-mcp/src/lib/forge.js
new file mode 100644
index 000000000..8fe28ed9a
--- /dev/null
+++ b/packages/blender-mcp/src/lib/forge.js
@@ -0,0 +1,151 @@
+// Real HTTP access to the public three.ws Forge pipeline (/api/forge).
+//
+// Generation is auth-free and IP rate-limited, scoped to an anonymous client
+// handle. The default image lane (FLUX to TRELLIS) is free; the geometry lane
+// (Meshy/Tripo) is bring-your-own-key and the key travels as a request header,
+// never in a body or a URL.
+//
+// The contract mirrored here is the same one the three.ws Blender add-on and
+// ComfyUI nodes speak (integrations/_pyclient/three_ws_client.py).
+
+import { createWriteStream } from 'node:fs';
+import { mkdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { randomUUID } from 'node:crypto';
+
+import { FORGE_PROVIDER_KEY, THREE_WS_BASE, USER_AGENT } from '../config.js';
+
+const POLL_INTERVAL_MS = 2500;
+const REQUEST_TIMEOUT_MS = 30000;
+
+const CLIENT_HANDLE = randomUUID().replace(/-/g, '');
+
+function headers(extra) {
+ return {
+ accept: 'application/json',
+ 'x-forge-client': CLIENT_HANDLE,
+ 'user-agent': USER_AGENT,
+ ...(FORGE_PROVIDER_KEY ? { 'x-forge-provider-key': FORGE_PROVIDER_KEY } : {}),
+ ...extra,
+ };
+}
+
+async function forgeRequest(pathname, { method = 'GET', query, body } = {}) {
+ const url = new URL(`${THREE_WS_BASE}${pathname}`);
+ for (const [key, value] of Object.entries(query || {})) {
+ if (value === undefined || value === null || value === '') continue;
+ url.searchParams.set(key, String(value));
+ }
+
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+ let res;
+ try {
+ res = await fetch(url, {
+ method,
+ headers: headers(body !== undefined ? { 'content-type': 'application/json' } : undefined),
+ body: body !== undefined ? JSON.stringify(body) : undefined,
+ signal: controller.signal,
+ });
+ } catch (err) {
+ clearTimeout(timer);
+ if (err?.name === 'AbortError') {
+ throw Object.assign(new Error(`three.ws ${pathname} timed out after ${REQUEST_TIMEOUT_MS}ms`), { code: 'timeout' });
+ }
+ throw Object.assign(new Error(`three.ws ${pathname} request failed: ${err?.message || err}`), {
+ code: 'network_error',
+ });
+ }
+ clearTimeout(timer);
+
+ const text = await res.text();
+ let data;
+ try {
+ data = text ? JSON.parse(text) : {};
+ } catch {
+ data = { raw: text };
+ }
+ if (!res.ok) {
+ const message = data?.message || data?.error || `three.ws ${pathname} returned HTTP ${res.status}`;
+ throw Object.assign(new Error(message), { code: 'upstream_error', status: res.status, body: data });
+ }
+ return data;
+}
+
+/** Live tier / backend / cost matrix for this deployment. */
+export async function catalog() {
+ return forgeRequest('/api/forge', { query: { catalog: '1' } });
+}
+
+/**
+ * Submit a text prompt for generation and return the queued job.
+ * @returns {Promise<{job_id: string, backend?: string}>}
+ */
+export async function submitTextTo3d({ prompt, tier = 'standard', backend, aspect_ratio = '1:1', lane = 'image' }) {
+ const body = { prompt, tier, path: lane, aspect_ratio };
+ if (backend) body.backend = backend;
+ const result = await forgeRequest('/api/forge', { method: 'POST', body });
+
+ if (result.error === 'needs_key') {
+ throw Object.assign(
+ new Error(
+ 'The Meshy/Tripo geometry lane needs your own provider key. Set THREE_WS_FORGE_PROVIDER_KEY, ' +
+ 'or use the free image lane (lane: "image").',
+ ),
+ { code: 'needs_key' },
+ );
+ }
+ if (result.error) {
+ throw Object.assign(new Error(result.message || result.error), { code: result.error });
+ }
+ if (!result.job_id) {
+ throw Object.assign(new Error('Forge accepted the prompt but returned no job id.'), { code: 'no_job' });
+ }
+ return result;
+}
+
+/**
+ * Poll a generation to completion.
+ * @returns {Promise<{glb_url: string, backend?: string, elapsed_ms: number, polls: number}>}
+ */
+export async function waitForGlb(jobId, { timeoutMs, onProgress } = {}) {
+ const started = Date.now();
+ let polls = 0;
+ for (;;) {
+ const result = await forgeRequest('/api/forge', { query: { job: jobId } });
+ polls += 1;
+ const status = result.status || 'running';
+ if (onProgress) onProgress(status, Date.now() - started);
+ if (status === 'done' && result.glb_url) {
+ return { ...result, elapsed_ms: Date.now() - started, polls };
+ }
+ if (status === 'failed') {
+ throw Object.assign(new Error(result.error || 'Generation failed.'), { code: 'generation_failed' });
+ }
+ if (Date.now() - started > timeoutMs) {
+ throw Object.assign(
+ new Error(`Generation ${jobId} was still "${status}" after ${Math.round((Date.now() - started) / 1000)}s.`),
+ { code: 'timeout', job_id: jobId },
+ );
+ }
+ await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+ }
+}
+
+/** Stream a generated GLB to disk and return its absolute path and size. */
+export async function downloadGlb(url, destination) {
+ const target = path.resolve(destination);
+ await mkdir(path.dirname(target), { recursive: true });
+ const res = await fetch(url, { headers: { 'user-agent': USER_AGENT } });
+ if (!res.ok || !res.body) {
+ throw Object.assign(new Error(`Downloading the generated GLB failed with HTTP ${res.status}.`), {
+ code: 'download_failed',
+ status: res.status,
+ });
+ }
+ await pipeline(Readable.fromWeb(res.body), createWriteStream(target));
+ const { size } = await stat(target);
+ return { path: target, bytes: size };
+}
diff --git a/packages/blender-mcp/src/lib/paths.js b/packages/blender-mcp/src/lib/paths.js
new file mode 100644
index 000000000..0ca6d33b1
--- /dev/null
+++ b/packages/blender-mcp/src/lib/paths.js
@@ -0,0 +1,43 @@
+// Path handling shared by the tools.
+//
+// Callers may pass a relative path (resolved against the server's working
+// directory) or an absolute one. Outputs are optional everywhere: when omitted
+// the file lands in BLENDER_MCP_WORKDIR under a name derived from the input, so
+// an agent can chain calls without inventing a filesystem layout.
+
+import { access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+
+import { WORKDIR } from '../config.js';
+import { ensureWorkdir } from './blender.js';
+
+/** Resolve an input path and confirm it is readable, or throw a clean error. */
+export async function resolveInput(value, label = 'input') {
+ const raw = String(value ?? '').trim();
+ if (!raw) {
+ throw Object.assign(new Error(`${label} is required.`), { code: 'invalid_input' });
+ }
+ const resolved = path.resolve(raw);
+ try {
+ await access(resolved, constants.R_OK);
+ } catch {
+ throw Object.assign(new Error(`${label} file not found or unreadable: ${resolved}`), { code: 'input_not_found' });
+ }
+ return resolved;
+}
+
+/**
+ * Resolve an output path, defaulting into the workdir.
+ *
+ * @param {string|undefined} value Caller-supplied path, if any.
+ * @param {string} basis Path the default name is derived from.
+ * @param {string} extension Extension for the default name, with the dot.
+ */
+export async function resolveOutput(value, basis, extension) {
+ const raw = String(value ?? '').trim();
+ if (raw) return path.resolve(raw);
+ await ensureWorkdir();
+ const stem = path.basename(basis, path.extname(basis)) || 'blender';
+ return path.join(WORKDIR, `${stem}-${Date.now()}${extension}`);
+}
diff --git a/packages/blender-mcp/src/py/runner.py b/packages/blender-mcp/src/py/runner.py
new file mode 100644
index 000000000..442ea468f
--- /dev/null
+++ b/packages/blender-mcp/src/py/runner.py
@@ -0,0 +1,575 @@
+"""In-Blender job runner for @three-ws/blender-mcp.
+
+Blender is launched once per tool call as:
+
+ blender -b --factory-startup -noaudio --python runner.py -- <job.json> <result.json>
+
+The job file carries a single ``{"op": ..., ...}`` object; the result file
+receives a single JSON object. Results go to a FILE rather than stdout because
+Blender writes progress, addon chatter, and render statistics to stdout, and
+parsing a payload out of that stream is guesswork. If the result file is absent
+after the process exits, Blender crashed and the Node side says so.
+
+Only the Blender Python API is used, so this runs unmodified in Blender 3.x and
+4.x: every operator is resolved by name with fallbacks, and every keyword is
+filtered against the operator's own RNA before the call, which is what keeps the
+importer/exporter renames across releases from breaking a tool.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import math
+import os
+import sys
+import traceback
+
+import bpy
+from mathutils import Vector
+
+# Extension -> ordered candidate importer operators. The first one that exists
+# in the running Blender wins, which covers the 3.x -> 4.x operator renames
+# (obj/stl/ply moved from import_scene/import_mesh to wm.*).
+IMPORTERS = {
+ ".glb": ("import_scene.gltf",),
+ ".gltf": ("import_scene.gltf",),
+ ".fbx": ("import_scene.fbx",),
+ ".obj": ("wm.obj_import", "import_scene.obj"),
+ ".stl": ("wm.stl_import", "import_mesh.stl"),
+ ".ply": ("wm.ply_import", "import_mesh.ply"),
+ ".dae": ("wm.collada_import",),
+ ".abc": ("wm.alembic_import",),
+ ".x3d": ("import_scene.x3d",),
+ ".usd": ("wm.usd_import",),
+ ".usda": ("wm.usd_import",),
+ ".usdc": ("wm.usd_import",),
+ ".usdz": ("wm.usd_import",),
+}
+
+EXPORTERS = {
+ ".glb": ("export_scene.gltf",),
+ ".gltf": ("export_scene.gltf",),
+ ".fbx": ("export_scene.fbx",),
+ ".obj": ("wm.obj_export", "export_scene.obj"),
+ ".stl": ("wm.stl_export", "export_mesh.stl"),
+ ".ply": ("wm.ply_export", "export_mesh.ply"),
+ ".dae": ("wm.collada_export",),
+ ".abc": ("wm.alembic_export",),
+ ".x3d": ("export_scene.x3d",),
+ ".usd": ("wm.usd_export",),
+ ".usda": ("wm.usd_export",),
+ ".usdc": ("wm.usd_export",),
+ ".usdz": ("wm.usd_export",),
+}
+
+
+class JobError(Exception):
+ """A job failed for a reason the caller can act on."""
+
+ def __init__(self, message, code="blender_error"):
+ super().__init__(message)
+ self.code = code
+
+
+def resolve_op(name):
+ """Return the ``bpy.ops`` callable for ``group.operator``, or None.
+
+ ``bpy.ops`` resolves attributes lazily and hands back a callable stub for
+ operators that do not exist in this build, so ``hasattr`` and ``getattr``
+ both lie. Asking for the RNA type is what actually proves registration: a
+ Blender shipped without USD, Collada, or Alembic raises KeyError here, and
+ the format is then reported as unsupported up front instead of failing
+ halfway through an export.
+ """
+ group_name, _, op_name = name.partition(".")
+ group = getattr(bpy.ops, group_name, None)
+ if group is None:
+ return None
+ op = getattr(group, op_name, None)
+ if op is None:
+ return None
+ try:
+ op.get_rna_type()
+ except (KeyError, RuntimeError, AttributeError):
+ return None
+ return op
+
+
+def first_op(candidates, kind, ext):
+ for name in candidates:
+ op = resolve_op(name)
+ if op is not None:
+ return op
+ raise JobError(
+ f"This Blender build has no {kind} for '{ext}'. Enable the matching add-on or use another format.",
+ code="format_unsupported",
+ )
+
+
+def call_op(op, **kwargs):
+ """Call an operator with only the keywords its RNA actually declares.
+
+ Blender renames exporter properties between releases (``export_apply`` on
+ the glTF exporter, ``use_mesh_modifiers`` on FBX, ``apply_modifiers`` on
+ OBJ). Filtering here lets one caller pass the superset and stay correct on
+ every version instead of guessing per release.
+ """
+ accepted = {prop.identifier for prop in op.get_rna_type().properties}
+ return op(**{key: value for key, value in kwargs.items() if key in accepted})
+
+
+def reset_scene():
+ """Start from a genuinely empty scene (no default cube, camera, or light)."""
+ bpy.ops.wm.read_factory_settings(use_empty=True)
+
+
+def load_input(path):
+ """Open a .blend, or import any other supported file into an empty scene."""
+ path = os.path.abspath(path)
+ if not os.path.isfile(path):
+ raise JobError(f"Input file not found: {path}", code="input_not_found")
+ ext = os.path.splitext(path)[1].lower()
+ if ext == ".blend":
+ bpy.ops.wm.open_mainfile(filepath=path)
+ return path
+ reset_scene()
+ candidates = IMPORTERS.get(ext)
+ if not candidates:
+ raise JobError(
+ f"Unsupported input format '{ext}'. Supported: {', '.join(sorted(IMPORTERS))}, .blend",
+ code="format_unsupported",
+ )
+ op = first_op(candidates, "importer", ext)
+ call_op(op, filepath=path)
+ return path
+
+
+def mesh_objects():
+ return [obj for obj in bpy.context.scene.objects if obj.type == "MESH"]
+
+
+def triangle_count(obj, depsgraph):
+ """Evaluated triangle count, so modifiers and subdivision are included."""
+ evaluated = obj.evaluated_get(depsgraph)
+ try:
+ mesh = evaluated.to_mesh()
+ except RuntimeError:
+ return 0, 0
+ if mesh is None:
+ return 0, 0
+ try:
+ mesh.calc_loop_triangles()
+ return len(mesh.loop_triangles), len(mesh.vertices)
+ finally:
+ evaluated.to_mesh_clear()
+
+
+def world_bounds(objects):
+ """Axis-aligned world-space bounds of ``objects`` as (min, max, center, radius)."""
+ corners = []
+ for obj in objects:
+ for corner in obj.bound_box:
+ corners.append(obj.matrix_world @ Vector(corner))
+ if not corners:
+ return None
+ lo = Vector((min(c.x for c in corners), min(c.y for c in corners), min(c.z for c in corners)))
+ hi = Vector((max(c.x for c in corners), max(c.y for c in corners), max(c.z for c in corners)))
+ center = (lo + hi) / 2.0
+ radius = max((corner - center).length for corner in corners)
+ return lo, hi, center, radius
+
+
+def scene_summary(include_objects=True):
+ depsgraph = bpy.context.evaluated_depsgraph_get()
+ objects = []
+ total_tris = 0
+ total_verts = 0
+ for obj in bpy.context.scene.objects:
+ entry = {
+ "name": obj.name,
+ "type": obj.type,
+ "parent": obj.parent.name if obj.parent else None,
+ "location": [round(v, 6) for v in obj.location],
+ "dimensions": [round(v, 6) for v in obj.dimensions],
+ "modifiers": [m.type for m in obj.modifiers],
+ "materials": [slot.material.name for slot in obj.material_slots if slot.material],
+ }
+ if obj.type == "MESH":
+ tris, verts = triangle_count(obj, depsgraph)
+ entry["triangles"] = tris
+ entry["vertices"] = verts
+ entry["uv_layers"] = [uv.name for uv in obj.data.uv_layers]
+ entry["shape_keys"] = len(obj.data.shape_keys.key_blocks) if obj.data.shape_keys else 0
+ total_tris += tris
+ total_verts += verts
+ if obj.type == "ARMATURE":
+ entry["bones"] = [bone.name for bone in obj.data.bones]
+ objects.append(entry)
+
+ bounds = world_bounds([obj for obj in bpy.context.scene.objects if obj.type in {"MESH", "CURVE", "SURFACE"}])
+ animations = []
+ for action in bpy.data.actions:
+ start, end = action.frame_range
+ animations.append(
+ {
+ "name": action.name,
+ "frame_start": round(start, 3),
+ "frame_end": round(end, 3),
+ "channels": len(action.fcurves),
+ }
+ )
+
+ summary = {
+ "scene": bpy.context.scene.name,
+ "unit_system": bpy.context.scene.unit_settings.system,
+ "frame_start": bpy.context.scene.frame_start,
+ "frame_end": bpy.context.scene.frame_end,
+ "counts": {
+ "objects": len(bpy.context.scene.objects),
+ "meshes": len(mesh_objects()),
+ "armatures": len([o for o in bpy.context.scene.objects if o.type == "ARMATURE"]),
+ "cameras": len([o for o in bpy.context.scene.objects if o.type == "CAMERA"]),
+ "lights": len([o for o in bpy.context.scene.objects if o.type == "LIGHT"]),
+ "materials": len(bpy.data.materials),
+ "images": len(bpy.data.images),
+ "actions": len(bpy.data.actions),
+ "triangles": total_tris,
+ "vertices": total_verts,
+ },
+ "materials": [mat.name for mat in bpy.data.materials],
+ "animations": animations,
+ }
+ if bounds:
+ lo, hi, center, radius = bounds
+ summary["bounds"] = {
+ "min": [round(v, 6) for v in lo],
+ "max": [round(v, 6) for v in hi],
+ "center": [round(v, 6) for v in center],
+ "size": [round(hi[i] - lo[i], 6) for i in range(3)],
+ "radius": round(radius, 6),
+ }
+ if include_objects:
+ summary["objects"] = objects
+ return summary
+
+
+def op_scene_info(job):
+ path = load_input(job["input"])
+ summary = scene_summary(include_objects=job.get("include_objects", True))
+ summary["input"] = path
+ summary["input_bytes"] = os.path.getsize(path)
+ return summary
+
+
+def apply_scale(factor):
+ if not factor or abs(factor - 1.0) < 1e-9:
+ return
+ for obj in bpy.context.scene.objects:
+ if obj.parent is None:
+ obj.scale = obj.scale * factor
+
+
+def export_to(path, *, apply_modifiers=True):
+ path = os.path.abspath(path)
+ parent = os.path.dirname(path)
+ if parent:
+ os.makedirs(parent, exist_ok=True)
+ ext = os.path.splitext(path)[1].lower()
+ if ext == ".blend":
+ bpy.ops.wm.save_as_mainfile(filepath=path, copy=True)
+ return path
+ candidates = EXPORTERS.get(ext)
+ if not candidates:
+ raise JobError(
+ f"Unsupported output format '{ext}'. Supported: {', '.join(sorted(EXPORTERS))}, .blend",
+ code="format_unsupported",
+ )
+ op = first_op(candidates, "exporter", ext)
+ call_op(
+ op,
+ filepath=path,
+ export_format="GLB" if ext == ".glb" else "GLTF_SEPARATE",
+ # Modifier application under the three names Blender's exporters use.
+ export_apply=apply_modifiers,
+ use_mesh_modifiers=apply_modifiers,
+ apply_modifiers=apply_modifiers,
+ check_existing=False,
+ )
+ if not os.path.isfile(path):
+ raise JobError(f"The exporter reported success but wrote no file at {path}", code="export_failed")
+ return path
+
+
+def op_convert(job):
+ load_input(job["input"])
+ apply_scale(job.get("scale"))
+ bpy.context.view_layer.update()
+ output = export_to(job["output"], apply_modifiers=job.get("apply_modifiers", True))
+ summary = scene_summary(include_objects=False)
+ return {
+ "input": os.path.abspath(job["input"]),
+ "output": output,
+ "output_bytes": os.path.getsize(output),
+ "counts": summary["counts"],
+ "bounds": summary.get("bounds"),
+ }
+
+
+# Engines worth probing for, best first. The static RNA enum is not a reliable
+# list: on some distro builds Cycles is assignable while absent from the enum,
+# so capability is decided by whether the assignment actually takes.
+CANDIDATE_ENGINES = ("CYCLES", "BLENDER_EEVEE_NEXT", "BLENDER_EEVEE", "BLENDER_WORKBENCH")
+
+
+def available_engines():
+ scene = bpy.context.scene
+ if scene is None:
+ return []
+ declared = [item.identifier for item in bpy.types.RenderSettings.bl_rna.properties["engine"].enum_items]
+ original = scene.render.engine
+ found = []
+ for name in list(CANDIDATE_ENGINES) + [e for e in declared if e not in CANDIDATE_ENGINES]:
+ if name in found:
+ continue
+ try:
+ scene.render.engine = name
+ except (TypeError, ValueError):
+ continue
+ found.append(name)
+ scene.render.engine = original
+ return found
+
+
+def enable_cycles():
+ """Cycles ships as a bundled add-on, and --factory-startup leaves it off.
+
+ Without this a headless container reports EEVEE as the only engine, and
+ EEVEE needs a real GPU context that most containers do not have.
+ """
+ if "CYCLES" in available_engines():
+ return True
+ try:
+ bpy.ops.preferences.addon_enable(module="cycles")
+ except Exception:
+ return False
+ return "CYCLES" in available_engines()
+
+
+def resolve_engine(requested):
+ enable_cycles()
+ engines = available_engines()
+ if requested and requested != "auto":
+ if requested in engines:
+ return requested
+ # EEVEE was renamed BLENDER_EEVEE_NEXT in Blender 4.2.
+ alias = "BLENDER_EEVEE_NEXT" if requested == "BLENDER_EEVEE" else "BLENDER_EEVEE"
+ if alias in engines:
+ return alias
+ raise JobError(
+ f"Render engine '{requested}' is not available. This build offers: {', '.join(engines)}",
+ code="engine_unavailable",
+ )
+ # CYCLES is the default because it renders on CPU. EEVEE needs a real GPU
+ # context, which a headless container usually does not have.
+ return "CYCLES" if "CYCLES" in engines else engines[0]
+
+
+def ensure_camera(scene, target_objects):
+ if scene.camera is not None:
+ return scene.camera, False
+ bounds = world_bounds(target_objects)
+ camera_data = bpy.data.cameras.new("three_ws_camera")
+ camera = bpy.data.objects.new("three_ws_camera", camera_data)
+ scene.collection.objects.link(camera)
+ scene.camera = camera
+ if bounds is None:
+ camera.location = Vector((4.0, -4.0, 3.0))
+ center = Vector((0.0, 0.0, 0.0))
+ else:
+ _lo, _hi, center, radius = bounds
+ radius = max(radius, 1e-4)
+ direction = Vector((1.0, -1.35, 0.75)).normalized()
+ distance = (radius / math.sin(camera_data.angle / 2.0)) * 1.05
+ camera.location = center + direction * distance
+ camera_data.clip_start = max(distance / 1000.0, 1e-4)
+ camera_data.clip_end = distance * 10.0
+ camera.rotation_euler = (center - camera.location).to_track_quat("-Z", "Y").to_euler()
+ return camera, True
+
+
+def ensure_lighting(scene):
+ """Add a key light and a lit world only when the scene has neither."""
+ added = []
+ if not any(obj.type == "LIGHT" for obj in scene.objects):
+ sun_data = bpy.data.lights.new("three_ws_key", type="SUN")
+ sun_data.energy = 4.0
+ sun = bpy.data.objects.new("three_ws_key", sun_data)
+ scene.collection.objects.link(sun)
+ sun.location = Vector((4.0, -6.0, 8.0))
+ sun.rotation_euler = (Vector((0.0, 0.0, 0.0)) - sun.location).to_track_quat("-Z", "Y").to_euler()
+ added.append("sun")
+ if scene.world is None:
+ scene.world = bpy.data.worlds.new("three_ws_world")
+ added.append("world")
+ scene.world.use_nodes = True
+ background = scene.world.node_tree.nodes.get("Background")
+ if background is not None and not added:
+ return added
+ if background is not None:
+ background.inputs[0].default_value = (0.05, 0.05, 0.06, 1.0)
+ background.inputs[1].default_value = 1.0
+ return added
+
+
+def render_still(scene):
+ """Render one frame, falling back to a denoiser-free pass if needed.
+
+ Blender builds without OpenImageDenoise (several Linux distro packages) fail
+ the whole render rather than the denoise step, so a preview that would
+ otherwise be fine dies on a post-process nobody asked for. Retry once
+ without it and report which pass produced the image.
+ """
+ try:
+ bpy.ops.render.render(write_still=True)
+ return bool(getattr(scene, "cycles", None) and scene.cycles.use_denoising)
+ except RuntimeError as exc:
+ if "denois" not in str(exc).lower() or not hasattr(scene, "cycles"):
+ raise
+ scene.cycles.use_denoising = False
+ bpy.ops.render.render(write_still=True)
+ return False
+
+
+def op_render(job):
+ load_input(job["input"])
+ scene = bpy.context.scene
+ engine = resolve_engine(job.get("engine", "auto"))
+ scene.render.engine = engine
+
+ samples = int(job.get("samples", 32))
+ if engine == "CYCLES":
+ scene.cycles.samples = samples
+ scene.cycles.use_denoising = True
+ scene.cycles.device = "CPU"
+ elif hasattr(scene, "eevee"):
+ scene.eevee.taa_render_samples = samples
+
+ width, height = job.get("resolution", [960, 960])
+ scene.render.resolution_x = int(width)
+ scene.render.resolution_y = int(height)
+ scene.render.resolution_percentage = 100
+ scene.render.image_settings.file_format = "PNG"
+ scene.render.image_settings.color_mode = "RGBA" if job.get("transparent", False) else "RGB"
+ scene.render.film_transparent = bool(job.get("transparent", False))
+
+ camera, camera_added = ensure_camera(scene, mesh_objects())
+ lights_added = ensure_lighting(scene)
+
+ output = os.path.abspath(job["output"])
+ parent = os.path.dirname(output)
+ if parent:
+ os.makedirs(parent, exist_ok=True)
+ scene.render.filepath = output
+ denoised = render_still(scene)
+ if not os.path.isfile(output):
+ raise JobError(f"Blender rendered but wrote no image at {output}", code="render_failed")
+ return {
+ "input": os.path.abspath(job["input"]),
+ "output": output,
+ "output_bytes": os.path.getsize(output),
+ "engine": engine,
+ "samples": samples,
+ "resolution": [scene.render.resolution_x, scene.render.resolution_y],
+ "camera": camera.name,
+ "denoised": denoised,
+ "camera_created": camera_added,
+ "lights_created": lights_added,
+ }
+
+
+def op_exec(job):
+ if job.get("input"):
+ load_input(job["input"])
+ else:
+ reset_scene()
+ captured = io.StringIO()
+ namespace = {"bpy": bpy, "Vector": Vector, "math": math, "__name__": "three_ws_blender_mcp"}
+ with contextlib.redirect_stdout(captured):
+ exec(compile(job["code"], "<three-ws-blender-mcp>", "exec"), namespace)
+ result = namespace.get("result")
+ try:
+ json.dumps(result)
+ except TypeError:
+ result = repr(result)
+ payload = {"stdout": captured.getvalue(), "result": result, "counts": scene_summary(include_objects=False)["counts"]}
+ if job.get("output"):
+ payload["output"] = export_to(job["output"], apply_modifiers=job.get("apply_modifiers", True))
+ payload["output_bytes"] = os.path.getsize(payload["output"])
+ return payload
+
+
+def op_probe(job):
+ """Report what this Blender build can actually do. No scene is touched."""
+ enable_cycles()
+ return {
+ "blender_version": bpy.app.version_string,
+ "blender_version_tuple": list(bpy.app.version),
+ "python_version": sys.version.split()[0],
+ "binary": bpy.app.binary_path,
+ "background": bpy.app.background,
+ "render_engines": available_engines(),
+ "import_formats": sorted(ext for ext, ops in IMPORTERS.items() if any(resolve_op(o) for o in ops)),
+ "export_formats": sorted(ext for ext, ops in EXPORTERS.items() if any(resolve_op(o) for o in ops)),
+ }
+
+
+OPS = {
+ "probe": op_probe,
+ "scene_info": op_scene_info,
+ "convert": op_convert,
+ "render": op_render,
+ "exec": op_exec,
+}
+
+
+def dispatch(job):
+ op_name = job.get("op")
+ handler = OPS.get(op_name)
+ if handler is None:
+ raise JobError(f"Unknown op '{op_name}'. Known ops: {', '.join(sorted(OPS))}", code="unknown_op")
+ payload = handler(job)
+ payload["ok"] = True
+ payload.setdefault("blender_version", bpy.app.version_string)
+ return payload
+
+
+def main():
+ argv = sys.argv
+ if "--" not in argv:
+ sys.stderr.write("runner.py expects: blender -b --python runner.py -- <job.json> <result.json>\n")
+ raise SystemExit(2)
+ args = argv[argv.index("--") + 1 :]
+ if len(args) < 2:
+ sys.stderr.write("runner.py expects a job path and a result path\n")
+ raise SystemExit(2)
+ job_path, result_path = args[0], args[1]
+ with open(job_path, "r", encoding="utf-8") as handle:
+ job = json.load(handle)
+ try:
+ payload = dispatch(job)
+ except JobError as exc:
+ payload = {"ok": False, "error": exc.code, "message": str(exc)}
+ except Exception as exc: # noqa: BLE001 - every failure must reach the caller as JSON
+ payload = {
+ "ok": False,
+ "error": "blender_error",
+ "message": f"{type(exc).__name__}: {exc}",
+ "traceback": traceback.format_exc(limit=8),
+ }
+ with open(result_path, "w", encoding="utf-8") as handle:
+ json.dump(payload, handle)
+
+
+main()
diff --git a/packages/blender-mcp/src/tools/convert.js b/packages/blender-mcp/src/tools/convert.js
new file mode 100644
index 000000000..c973f4a4b
--- /dev/null
+++ b/packages/blender-mcp/src/tools/convert.js
@@ -0,0 +1,51 @@
+// `blender_convert`: import one 3D format, export another.
+//
+// Blender is the most complete format bridge available offline, so this is the
+// tool that turns an FBX or USD a client sent into the GLB the three.ws
+// pipeline consumes, and back again. Modifiers are applied by default so the
+// exported geometry matches what the file looks like on screen.
+
+import { z } from 'zod';
+
+import { runJob } from '../lib/blender.js';
+import { resolveInput, resolveOutput } from '../lib/paths.js';
+
+export const def = {
+ name: 'blender_convert',
+ title: 'Convert a 3D file between formats',
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+ description:
+ 'Convert a 3D file from any format Blender can import to any format it can export, driven entirely by the ' +
+ 'file extensions: .glb, .gltf, .fbx, .obj, .stl, .ply, .dae, .abc, .usd/.usda/.usdc/.usdz, .x3d, and .blend ' +
+ 'on both sides. Modifiers are applied on export by default, and an optional uniform scale is baked in. ' +
+ 'Returns the output path, its size, the resulting geometry counts, and the world-space bounds. The input ' +
+ 'file is never modified; omit "output" and the result lands in the server workdir.',
+ inputSchema: {
+ input: z.string().min(1).describe('Path to the source 3D file.'),
+ output: z
+ .string()
+ .optional()
+ .describe('Destination path. Its extension selects the export format. Defaults to a .glb in the server workdir.'),
+ apply_modifiers: z
+ .boolean()
+ .optional()
+ .describe('Apply modifiers (subdivision, decimate, mirror) to the exported geometry. Default true.'),
+ scale: z
+ .number()
+ .positive()
+ .optional()
+ .describe('Uniform scale factor baked into the export, e.g. 0.01 to convert centimetre units to metres.'),
+ },
+ async handler(args) {
+ const input = await resolveInput(args?.input);
+ const output = await resolveOutput(args?.output, input, '.glb');
+ const payload = await runJob({
+ op: 'convert',
+ input,
+ output,
+ apply_modifiers: args?.apply_modifiers !== false,
+ scale: args?.scale,
+ });
+ return { ...payload, ok: true };
+ },
+};
diff --git a/packages/blender-mcp/src/tools/forge-import.js b/packages/blender-mcp/src/tools/forge-import.js
new file mode 100644
index 000000000..b92e0e543
--- /dev/null
+++ b/packages/blender-mcp/src/tools/forge-import.js
@@ -0,0 +1,90 @@
+// `blender_forge_import`: text prompt to a 3D model, open in Blender.
+//
+// Bridges the public three.ws Forge pipeline into the local Blender session: a
+// prompt is generated on the free image lane (FLUX to TRELLIS), the resulting
+// GLB is downloaded, and it is either kept as-is or converted into whatever the
+// output extension asks for, .blend included. That closes the loop between "an
+// agent needs an asset" and "the asset is in a scene it can edit".
+
+import { z } from 'zod';
+
+import path from 'node:path';
+
+import { runJob } from '../lib/blender.js';
+import { downloadGlb, submitTextTo3d, waitForGlb } from '../lib/forge.js';
+import { resolveOutput } from '../lib/paths.js';
+import { FORGE_TIMEOUT_MS } from '../config.js';
+
+function slug(prompt) {
+ return (
+ prompt
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, '-')
+ .replace(/^-+|-+$/g, '')
+ .slice(0, 40) || 'forge'
+ );
+}
+
+export const def = {
+ name: 'blender_forge_import',
+ title: 'Generate a 3D model with three.ws and open it in Blender',
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+ description:
+ 'Generate a 3D model from a text prompt on the public three.ws Forge pipeline, then bring it into Blender. ' +
+ 'The default image lane (FLUX to TRELLIS) is free and needs no key, wallet, or account. The GLB is saved ' +
+ 'locally, and if the output path asks for another format (.blend, .fbx, .obj, .usd) Blender converts it on ' +
+ 'the way in. Returns the local path, the hosted GLB URL, and the geometry counts. Generation runs on a ' +
+ 'shared GPU lane and typically takes tens of seconds to a couple of minutes. Describe ONE subject per call.',
+ inputSchema: {
+ prompt: z.string().min(3).describe('What to generate. One subject, e.g. "a weathered brass diving helmet".'),
+ output: z
+ .string()
+ .optional()
+ .describe('Where to save it. The extension picks the format (.glb keeps the original bytes). Defaults to a .glb in the workdir.'),
+ tier: z.enum(['draft', 'standard', 'high']).optional().describe('Generation quality. Default "standard".'),
+ lane: z
+ .enum(['image', 'geometry', 'sketch'])
+ .optional()
+ .describe('Pipeline lane. "image" (default) is free. "geometry" uses Meshy/Tripo and needs THREE_WS_FORGE_PROVIDER_KEY.'),
+ backend: z.string().optional().describe('Pin a specific backend. Omit to let the deployment choose for the tier.'),
+ aspect_ratio: z.enum(['1:1', '4:3', '3:4', '16:9', '9:16']).optional().describe('Reference image aspect ratio. Default "1:1".'),
+ },
+ async handler(args) {
+ const prompt = String(args?.prompt ?? '').trim();
+ const submitted = await submitTextTo3d({
+ prompt,
+ tier: args?.tier || 'standard',
+ backend: args?.backend,
+ aspect_ratio: args?.aspect_ratio || '1:1',
+ lane: args?.lane || 'image',
+ });
+ const finished = await waitForGlb(submitted.job_id, { timeoutMs: FORGE_TIMEOUT_MS });
+
+ const output = await resolveOutput(args?.output, slug(prompt), '.glb');
+ const keepsOriginalBytes = output.toLowerCase().endsWith('.glb');
+ // When the caller asked for another format, the untouched GLB is kept
+ // beside it: conversion is lossy for some targets, and the original is
+ // what the three.ws pipeline consumes downstream.
+ const sourceGlb = path.join(path.dirname(output), `${path.basename(output, path.extname(output))}.source.glb`);
+ const download = await downloadGlb(finished.glb_url, keepsOriginalBytes ? output : sourceGlb);
+
+ const scene = keepsOriginalBytes
+ ? await runJob({ op: 'scene_info', input: download.path, include_objects: false })
+ : await runJob({ op: 'convert', input: download.path, output });
+
+ return {
+ ok: true,
+ prompt,
+ job_id: submitted.job_id,
+ backend: finished.backend || submitted.backend,
+ glb_url: finished.glb_url,
+ output: keepsOriginalBytes ? download.path : scene.output,
+ output_bytes: keepsOriginalBytes ? download.bytes : scene.output_bytes,
+ source_glb: keepsOriginalBytes ? null : download.path,
+ generation_ms: finished.elapsed_ms,
+ counts: scene.counts,
+ bounds: scene.bounds,
+ blender_version: scene.blender_version,
+ };
+ },
+};
diff --git a/packages/blender-mcp/src/tools/info.js b/packages/blender-mcp/src/tools/info.js
new file mode 100644
index 000000000..47e795abc
--- /dev/null
+++ b/packages/blender-mcp/src/tools/info.js
@@ -0,0 +1,38 @@
+// `blender_info`: report the Blender this server will actually drive.
+//
+// Every other tool depends on a working Blender, so this is the first call to
+// make when something misbehaves: it resolves the executable, reports the
+// version and bundled Python, and lists the render engines and file formats
+// this specific build can handle. A distro package with a stripped add-on set
+// shows up here rather than as a confusing failure three calls later.
+
+import { runJob } from '../lib/blender.js';
+import { ALLOW_PYTHON, WORKDIR } from '../config.js';
+
+export const def = {
+ name: 'blender_info',
+ title: 'Inspect the local Blender install',
+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+ description:
+ 'Report the local Blender this server drives: executable path, version, bundled Python, available render ' +
+ 'engines, and the import/export formats this build actually supports. Call it first when a tool fails, or ' +
+ 'to check that Blender is installed at all. Read-only: it opens no file and writes nothing.',
+ inputSchema: {},
+ async handler() {
+ const payload = await runJob({ op: 'probe' }, { timeoutMs: 120000 });
+ return {
+ ok: true,
+ blender: {
+ path: payload.blender_path,
+ version: payload.blender_version,
+ python: payload.python_version,
+ background: payload.background,
+ },
+ render_engines: payload.render_engines,
+ import_formats: payload.import_formats,
+ export_formats: payload.export_formats,
+ workdir: WORKDIR,
+ python_tool_enabled: ALLOW_PYTHON,
+ };
+ },
+};
diff --git a/packages/blender-mcp/src/tools/render.js b/packages/blender-mcp/src/tools/render.js
new file mode 100644
index 000000000..67ee346de
--- /dev/null
+++ b/packages/blender-mcp/src/tools/render.js
@@ -0,0 +1,59 @@
+// `blender_render`: render a still preview of a 3D file.
+//
+// The point is a preview an agent can look at without a viewport, so the tool
+// fills in what a bare asset file lacks: if the scene has no camera one is
+// created and framed to the geometry's bounding sphere, and if it has no light
+// a key light and a lit world are added. A scene that already carries its own
+// camera and lighting is rendered exactly as authored.
+//
+// CYCLES is the default engine because it renders on CPU; EEVEE needs a real
+// GPU context, which a headless container usually does not have.
+
+import { z } from 'zod';
+
+import { runJob } from '../lib/blender.js';
+import { resolveInput, resolveOutput } from '../lib/paths.js';
+
+export const def = {
+ name: 'blender_render',
+ title: 'Render a preview image of a 3D file',
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+ description:
+ 'Render a still PNG of any 3D file Blender can open (.blend, .glb, .fbx, .obj, .usd and the rest). If the ' +
+ 'scene has no camera, one is created and framed to the model; if it has no light, a key light and a lit ' +
+ 'world are added, so a bare asset file renders as a usable preview with no setup. A scene that already has ' +
+ 'its own camera and lighting is rendered as authored. Returns the image path, the engine used, and whether ' +
+ 'a camera or lights had to be added. Use it to see a model, check a conversion, or produce a thumbnail.',
+ inputSchema: {
+ input: z.string().min(1).describe('Path to the 3D file to render.'),
+ output: z.string().optional().describe('Destination PNG path. Defaults to a .png in the server workdir.'),
+ engine: z
+ .enum(['auto', 'CYCLES', 'BLENDER_EEVEE', 'BLENDER_WORKBENCH'])
+ .optional()
+ .describe(
+ 'Render engine. "auto" (default) picks CYCLES, which renders on CPU. EEVEE is far faster but needs a GPU ' +
+ 'context. Call blender_info to see what this build offers.',
+ ),
+ samples: z.number().int().min(1).max(4096).optional().describe('Sample count. Default 32: enough for a preview.'),
+ resolution: z
+ .array(z.number().int().min(16).max(8192))
+ .length(2)
+ .optional()
+ .describe('Output size as [width, height]. Default [960, 960].'),
+ transparent: z.boolean().optional().describe('Render with a transparent background instead of the world. Default false.'),
+ },
+ async handler(args) {
+ const input = await resolveInput(args?.input);
+ const output = await resolveOutput(args?.output, input, '.png');
+ const payload = await runJob({
+ op: 'render',
+ input,
+ output,
+ engine: args?.engine || 'auto',
+ samples: args?.samples ?? 32,
+ resolution: args?.resolution ?? [960, 960],
+ transparent: args?.transparent === true,
+ });
+ return { ...payload, ok: true };
+ },
+};
diff --git a/packages/blender-mcp/src/tools/run-python.js b/packages/blender-mcp/src/tools/run-python.js
new file mode 100644
index 000000000..04a6f70d0
--- /dev/null
+++ b/packages/blender-mcp/src/tools/run-python.js
@@ -0,0 +1,52 @@
+// `blender_run_python`: run Python inside Blender against a scene.
+//
+// This is the escape hatch that makes the rest of the toolset composable:
+// decimate a mesh, rename bones, bake an animation, join objects, strip
+// materials. The script runs in Blender's own interpreter with `bpy` bound, so
+// anything the Blender Python API can do is reachable, and an optional export
+// writes the edited scene out in one call.
+//
+// The tool is powerful by design and therefore explicit about it: it is
+// annotated destructive, and setting BLENDER_MCP_ALLOW_PYTHON=0 removes it from
+// the advertised tool list entirely for unattended deployments.
+
+import { z } from 'zod';
+
+import { runJob } from '../lib/blender.js';
+import { resolveInput, resolveOutput } from '../lib/paths.js';
+
+export const def = {
+ name: 'blender_run_python',
+ title: 'Run a Python script inside Blender',
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+ description:
+ 'Execute a Python script inside Blender with the full bpy API available. Optionally open a 3D file first ' +
+ '(any format Blender imports) and export the edited scene afterwards, chosen by the output extension. ' +
+ 'Anything printed is returned as stdout, and assigning a JSON-serializable value to a variable named ' +
+ '`result` returns it as structured data. Use this for scene edits the other tools do not cover: decimating ' +
+ 'meshes, joining or renaming objects, editing armatures, baking animation, cleaning materials. The script ' +
+ 'runs with the permissions of this server and can read and write the local filesystem.',
+ inputSchema: {
+ code: z.string().min(1).describe('Python source to execute. `bpy`, `math`, and `Vector` are already imported.'),
+ input: z
+ .string()
+ .optional()
+ .describe('3D file to open before running the script. Omit to start from an empty scene.'),
+ output: z
+ .string()
+ .optional()
+ .describe('Export the scene here after the script runs; the extension selects the format. Omit to discard it.'),
+ apply_modifiers: z.boolean().optional().describe('Apply modifiers when exporting. Default true.'),
+ },
+ async handler(args) {
+ const job = {
+ op: 'exec',
+ code: String(args?.code ?? ''),
+ apply_modifiers: args?.apply_modifiers !== false,
+ };
+ if (args?.input) job.input = await resolveInput(args.input);
+ if (args?.output) job.output = await resolveOutput(args.output, job.input || 'scene', '.glb');
+ const payload = await runJob(job);
+ return { ...payload, ok: true };
+ },
+};
diff --git a/packages/blender-mcp/src/tools/scene-info.js b/packages/blender-mcp/src/tools/scene-info.js
new file mode 100644
index 000000000..4331699ba
--- /dev/null
+++ b/packages/blender-mcp/src/tools/scene-info.js
@@ -0,0 +1,37 @@
+// `blender_scene_info`: read a 3D file through Blender and describe it.
+//
+// Wraps the runner's scene_info op: open a .blend or import any supported
+// format into an empty scene, then report evaluated geometry (modifiers
+// applied), materials, armatures, animation actions, and world-space bounds.
+
+import { z } from 'zod';
+
+import { runJob } from '../lib/blender.js';
+import { resolveInput } from '../lib/paths.js';
+
+export const def = {
+ name: 'blender_scene_info',
+ title: 'Describe a 3D file with Blender',
+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+ description:
+ 'Open a 3D file with Blender and report what is inside it: object list with types, parents, dimensions and ' +
+ 'modifiers; evaluated triangle and vertex counts; materials; armature bone names; animation actions with ' +
+ 'their frame ranges; and world-space bounds. Accepts .blend plus every format this Blender can import ' +
+ '(.glb, .gltf, .fbx, .obj, .stl, .ply, .dae, .abc, .usd*, .x3d). Read-only: the file is never modified.',
+ inputSchema: {
+ input: z.string().min(1).describe('Path to the 3D file to inspect. Absolute, or relative to the server working directory.'),
+ include_objects: z
+ .boolean()
+ .optional()
+ .describe('Include the per-object breakdown. Set false on very large scenes to get totals only. Default true.'),
+ },
+ async handler(args) {
+ const input = await resolveInput(args?.input);
+ const payload = await runJob({
+ op: 'scene_info',
+ input,
+ include_objects: args?.include_objects !== false,
+ });
+ return { ...payload, ok: true };
+ },
+};
diff --git a/packages/blender-mcp/test/blender-session.test.mjs b/packages/blender-mcp/test/blender-session.test.mjs
new file mode 100644
index 000000000..d89ed9c72
--- /dev/null
+++ b/packages/blender-mcp/test/blender-session.test.mjs
@@ -0,0 +1,201 @@
+// End-to-end coverage against the real Blender on this machine, driven through
+// a real MCP stdio session (client SDK -> spawned server -> Blender).
+//
+// Nothing here is stubbed: a fixture GLB is produced by Blender itself, then
+// inspected, converted, rendered, and edited with a bpy script. The whole file
+// skips when no Blender is installed, so it stays green on a machine that only
+// runs the offline suite.
+//
+// Run: node --test packages/blender-mcp/test/blender-session.test.mjs
+
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, stat, readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+import { resolveBlender, runJob } from '../src/lib/blender.js';
+
+const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+// Resolved at module load, not in before(): node:test reads the `skip` option
+// when the test is DEFINED, so a promise or a callback there silently skips.
+const SKIP = (await resolveBlender().then(
+ () => false,
+ () => true,
+))
+ ? 'no Blender executable on this machine'
+ : false;
+
+let workdir;
+let client;
+let fixture;
+
+/** Parse the single text block an MCP tool result carries. */
+function payloadOf(result) {
+ return JSON.parse(result.content[0].text);
+}
+
+async function callTool(name, args) {
+ const result = await client.callTool({ name, arguments: args });
+ return { isError: result.isError === true, payload: payloadOf(result) };
+}
+
+before(async () => {
+ if (SKIP) return;
+
+ workdir = await mkdtemp(path.join(os.tmpdir(), 'blender-mcp-test-'));
+ fixture = path.join(workdir, 'fixture.glb');
+
+ // Build the fixture with Blender itself: a subdivided monkey with a
+ // material, so triangle counts, materials, and modifiers are all non-trivial.
+ await runJob({
+ op: 'exec',
+ code: [
+ 'import bpy',
+ 'bpy.ops.mesh.primitive_monkey_add(size=2)',
+ "obj = bpy.context.object",
+ "obj.name = 'Fixture'",
+ "material = bpy.data.materials.new('FixtureSkin')",
+ 'material.use_nodes = True',
+ 'obj.data.materials.append(material)',
+ "obj.modifiers.new('Subd', 'SUBSURF').levels = 1",
+ ].join('\n'),
+ output: fixture,
+ });
+
+ client = new Client({ name: 'blender-mcp-tests', version: '1.0.0' }, { capabilities: {} });
+ await client.connect(
+ new StdioClientTransport({
+ command: process.execPath,
+ args: [path.join(PACKAGE_ROOT, 'src', 'index.js')],
+ cwd: PACKAGE_ROOT,
+ env: { ...process.env, BLENDER_MCP_WORKDIR: workdir },
+ }),
+ );
+});
+
+after(async () => {
+ if (client) await client.close();
+ if (workdir) await rm(workdir, { recursive: true, force: true });
+});
+
+test('the session advertises every tool with a schema', { skip: SKIP }, async () => {
+ const { tools } = await client.listTools();
+ const names = tools.map((t) => t.name).sort();
+ assert.deepEqual(names, [
+ 'blender_convert',
+ 'blender_forge_import',
+ 'blender_info',
+ 'blender_render',
+ 'blender_run_python',
+ 'blender_scene_info',
+ ]);
+ for (const tool of tools) {
+ assert.equal(tool.inputSchema.type, 'object', `${tool.name} must publish an object schema`);
+ }
+});
+
+test('blender_info reports the local build', { skip: SKIP }, async () => {
+ const { isError, payload } = await callTool('blender_info', {});
+ assert.equal(isError, false);
+ assert.match(payload.blender.version, /^\d+\.\d+/);
+ assert.ok(payload.render_engines.length > 0, 'at least one render engine must be usable');
+ assert.ok(payload.import_formats.includes('.glb'), 'glTF import is required by the other tools');
+});
+
+test('blender_scene_info reports evaluated geometry, materials and bounds', { skip: SKIP }, async () => {
+ const { isError, payload } = await callTool('blender_scene_info', { input: fixture });
+ assert.equal(isError, false);
+ assert.equal(payload.counts.meshes, 1);
+ assert.ok(payload.counts.triangles > 100, 'the subdivided fixture should carry real geometry');
+ assert.deepEqual(payload.materials, ['FixtureSkin']);
+ assert.equal(payload.objects[0].name, 'Fixture');
+ assert.ok(payload.bounds.radius > 0);
+});
+
+test('blender_convert round-trips GLB to FBX and back with the geometry intact', { skip: SKIP }, async () => {
+ const source = await callTool('blender_scene_info', { input: fixture });
+ const fbx = path.join(workdir, 'round-trip.fbx');
+ const toFbx = await callTool('blender_convert', { input: fixture, output: fbx });
+ assert.equal(toFbx.isError, false);
+ assert.equal(toFbx.payload.output, fbx);
+ assert.ok((await stat(fbx)).size > 0);
+
+ const back = path.join(workdir, 'round-trip.glb');
+ const toGlb = await callTool('blender_convert', { input: fbx, output: back });
+ assert.equal(toGlb.isError, false);
+ assert.equal(toGlb.payload.counts.triangles, source.payload.counts.triangles);
+});
+
+test('blender_convert bakes a uniform scale into the export', { skip: SKIP }, async () => {
+ const output = path.join(workdir, 'scaled.glb');
+ const { payload } = await callTool('blender_convert', { input: fixture, output, scale: 2 });
+ const source = await callTool('blender_scene_info', { input: fixture });
+ assert.ok(
+ Math.abs(payload.bounds.size[0] - source.payload.bounds.size[0] * 2) < 1e-3,
+ 'a scale of 2 must double the exported bounds',
+ );
+});
+
+test('blender_render writes a real PNG, framing and lighting a bare asset', { skip: SKIP }, async () => {
+ const output = path.join(workdir, 'preview.png');
+ const { isError, payload } = await callTool('blender_render', {
+ input: fixture,
+ output,
+ samples: 4,
+ resolution: [160, 160],
+ });
+ assert.equal(isError, false);
+ assert.equal(payload.camera_created, true, 'the fixture has no camera, so one must be added');
+ assert.ok(payload.lights_created.includes('sun'), 'the fixture has no light, so one must be added');
+ const header = await readFile(output);
+ assert.deepEqual([...header.subarray(0, 4)], [0x89, 0x50, 0x4e, 0x47], 'the output must be a PNG');
+ assert.ok(header.length > 1000, 'the PNG must have real image data');
+});
+
+test('blender_run_python edits the scene and exports the result', { skip: SKIP }, async () => {
+ const output = path.join(workdir, 'decimated.glb');
+ const before = await callTool('blender_scene_info', { input: fixture });
+ const { isError, payload } = await callTool('blender_run_python', {
+ input: fixture,
+ output,
+ code: [
+ 'import bpy',
+ "obj = bpy.data.objects['Fixture']",
+ "modifier = obj.modifiers.new('Decimate', 'DECIMATE')",
+ 'modifier.ratio = 0.25',
+ "print('ratio', modifier.ratio)",
+ "result = {'object': obj.name}",
+ ].join('\n'),
+ });
+ assert.equal(isError, false);
+ assert.match(payload.stdout, /ratio 0\.25/);
+ assert.deepEqual(payload.result, { object: 'Fixture' });
+ assert.ok(
+ payload.counts.triangles < before.payload.counts.triangles / 2,
+ 'decimating to a quarter must cut the evaluated triangle count',
+ );
+});
+
+test('a missing input fails as a structured tool error, not a crash', { skip: SKIP }, async () => {
+ const { isError, payload } = await callTool('blender_scene_info', { input: path.join(workdir, 'nope.glb') });
+ assert.equal(isError, true);
+ assert.equal(payload.ok, false);
+ assert.equal(payload.error, 'input_not_found');
+ assert.match(payload.message, /not found/i);
+});
+
+test('an unsupported output format fails with an actionable message', { skip: SKIP }, async () => {
+ const { isError, payload } = await callTool('blender_convert', {
+ input: fixture,
+ output: path.join(workdir, 'nope.3mf'),
+ });
+ assert.equal(isError, true);
+ assert.equal(payload.error, 'format_unsupported');
+ assert.match(payload.message, /Supported:/);
+});
diff --git a/packages/blender-mcp/test/registration.test.mjs b/packages/blender-mcp/test/registration.test.mjs
new file mode 100644
index 000000000..0a35adc02
--- /dev/null
+++ b/packages/blender-mcp/test/registration.test.mjs
@@ -0,0 +1,98 @@
+// Tool-surface invariants for @three-ws/blender-mcp.
+//
+// Importing src/index.js is side-effect-free: the stdio transport only connects
+// when the file is the process entry point, and buildServer() neither launches
+// Blender nor touches the network. These tests run offline and pass on a
+// machine with no Blender installed.
+//
+// Run: node --test packages/blender-mcp/test/registration.test.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { TOOLS, buildServer } from '../src/index.js';
+
+const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+const READ_ONLY_TOOLS = new Set(['blender_info', 'blender_scene_info']);
+
+test('exactly the expected tools are registered', () => {
+ assert.deepEqual(
+ new Set(TOOLS.map((t) => t.name)),
+ new Set([
+ 'blender_info',
+ 'blender_scene_info',
+ 'blender_convert',
+ 'blender_render',
+ 'blender_forge_import',
+ 'blender_run_python',
+ ]),
+ );
+});
+
+test('every tool has a title, description, input schema and complete annotations', () => {
+ for (const tool of TOOLS) {
+ assert.equal(typeof tool.title, 'string', `${tool.name} is missing a title`);
+ assert.ok(tool.title.length > 0, `${tool.name} has an empty title`);
+ assert.equal(typeof tool.description, 'string', `${tool.name} is missing a description`);
+ assert.ok(tool.inputSchema && typeof tool.inputSchema === 'object', `${tool.name} is missing inputSchema`);
+ assert.equal(typeof tool.handler, 'function', `${tool.name} is missing a handler`);
+ assert.ok(tool.annotations, `${tool.name} is missing MCP ToolAnnotations`);
+ assert.equal(typeof tool.annotations.readOnlyHint, 'boolean', `${tool.name} must set readOnlyHint`);
+ assert.equal(typeof tool.annotations.idempotentHint, 'boolean', `${tool.name} must set idempotentHint`);
+ assert.equal(typeof tool.annotations.openWorldHint, 'boolean', `${tool.name} must set openWorldHint`);
+ }
+});
+
+test('non-read-only tools set destructiveHint explicitly (spec default is TRUE when omitted)', () => {
+ for (const tool of TOOLS) {
+ if (tool.annotations.readOnlyHint === false) {
+ assert.equal(
+ typeof tool.annotations.destructiveHint,
+ 'boolean',
+ `${tool.name} is not read-only; destructiveHint must be explicit`,
+ );
+ }
+ }
+});
+
+test('the read tools advertise readOnlyHint and stay inside the machine', () => {
+ for (const name of READ_ONLY_TOOLS) {
+ const tool = TOOLS.find((t) => t.name === name);
+ assert.ok(tool, `${name} must exist in the tool registry`);
+ assert.equal(tool.annotations.readOnlyHint, true, `${name} should be read-only`);
+ assert.equal(tool.annotations.openWorldHint, false, `${name} only drives the local Blender`);
+ }
+});
+
+test('blender_run_python is the only tool flagged destructive', () => {
+ const destructive = TOOLS.filter((t) => t.annotations.destructiveHint === true).map((t) => t.name);
+ assert.deepEqual(destructive, ['blender_run_python']);
+});
+
+test('blender_forge_import is the only tool that reaches the network', () => {
+ const openWorld = TOOLS.filter((t) => t.annotations.openWorldHint === true).map((t) => t.name);
+ assert.deepEqual(openWorld, ['blender_forge_import']);
+});
+
+test('BLENDER_MCP_ALLOW_PYTHON=0 withdraws the script tool', () => {
+ // The gate is read at module load, so it has to be checked in a fresh
+ // process: an ESM cache-buster on index.js would still reuse config.js.
+ const child = spawnSync(
+ process.execPath,
+ ['--input-type=module', '-e', "import('./src/index.js').then((m) => console.log(m.TOOLS.map((t) => t.name).join(',')))"],
+ { cwd: PACKAGE_ROOT, env: { ...process.env, BLENDER_MCP_ALLOW_PYTHON: '0' }, encoding: 'utf8' },
+ );
+ assert.equal(child.status, 0, child.stderr);
+ const names = child.stdout.trim().split(',');
+ assert.ok(!names.includes('blender_run_python'), 'blender_run_python must not be advertised when the gate is off');
+ assert.equal(names.length, 5);
+});
+
+test('buildServer registers without Blender or network access', () => {
+ const server = buildServer();
+ assert.ok(server, 'buildServer() must return an McpServer');
+});
diff --git a/prompts/store-submissions/_generated/mcp-listing-source.json b/prompts/store-submissions/_generated/mcp-listing-source.json
index dccd97d2f..3ccdce8f4 100644
--- a/prompts/store-submissions/_generated/mcp-listing-source.json
+++ b/prompts/store-submissions/_generated/mcp-listing-source.json
@@ -23,9 +23,9 @@
"icon": "Card/avatar image on all directories."
},
"counts": {
- "total": 50,
+ "total": 51,
"remote": 7,
- "stdio": 43
+ "stdio": 44
},
"servers": [
{
@@ -414,6 +414,37 @@
"registryUrl": "https://registry.modelcontextprotocol.io/?q=io.github.nirholas%2Fbilling-mcp",
"icon": "https://three.ws/three-ws-mcp-icon.svg"
},
+ {
+ "name": "io.github.nirholas/blender-mcp",
+ "title": "three.ws Blender",
+ "type": "stdio",
+ "transport": "stdio",
+ "connect": "npx -y @three-ws/blender-mcp",
+ "npmPackage": "@three-ws/blender-mcp",
+ "version": "0.1.0",
+ "description": "Drive a local Blender headlessly: inspect, convert, render and script 3D files.",
+ "tagline": "Drive the Blender on your own machine: inspect, convert, render and script 3D files, headless.",
+ "category": "3d",
+ "tags": [
+ "blender",
+ "gltf",
+ "fbx",
+ "usd",
+ "render",
+ "headless",
+ "pipeline"
+ ],
+ "examplePrompts": [
+ "What is inside this FBX: how many triangles, materials and bones?",
+ "Convert this FBX to a web-ready GLB in metres and render me a preview.",
+ "Halve the triangle count on every mesh and export it as a new GLB."
+ ],
+ "requiredEnv": [],
+ "websiteUrl": "https://three.ws",
+ "repository": "https://github.com/nirholas/three.ws",
+ "registryUrl": "https://registry.modelcontextprotocol.io/?q=io.github.nirholas%2Fblender-mcp",
+ "icon": "https://three.ws/three-ws-mcp-icon.svg"
+ },
{
"name": "io.github.nirholas/brain-mcp",
"title": "three.ws Brain",
diff --git a/public/changelog.json b/public/changelog.json
index 702bdfb30..1fa30b8c8 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,11 +1,22 @@
{
- "generated_at": "2026-09-05T16:25:38.047Z",
+ "generated_at": "2026-09-07T00:35:01.169Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
"entries": [
+ {
+ "date": "2026-09-07",
+ "type": "update",
+ "title": "Point an AI agent at the Blender on your own machine",
+ "summary": "A new MCP server drives the Blender you already have installed, with no GUI open and no add-on to install first. An assistant can now read a 3D file and tell you what is actually in it (objects, triangle counts, materials, bones, animations, real-world size), convert between GLB, glTF, FBX, OBJ, STL, PLY, Collada, Alembic, USD and .blend in either direction, render a preview image of a bare asset file that arrives with no camera or lighting of its own, and run a Blender Python script to do the things no single tool covers, like halving a mesh's triangle count and exporting the result in one step. It also reaches back into three.ws: describe something in a sentence and the free text-to-3D lane generates it and opens it in Blender. Blender runs in the background, one process per request, so it works the same on a laptop, a server, or in CI.",
+ "link": null,
+ "tags": [
+ "feature",
+ "sdk"
+ ]
+ },
{
"date": "2026-09-05",
"type": "launch",
@@ -163,6 +174,18 @@
"improvement"
]
},
+ {
+ "date": "2026-09-05",
+ "type": "update",
+ "title": "The VS Code extension now animates, refines, optimizes and reviews your models, and checks your embeds",
+ "summary": "Open a rigged model in VS Code, press Animate, and pick from the same 2,800-clip motion library the site uses: the clip is retargeted onto that model's own skeleton right in the editor, and Bake clip writes it into a copy of the file so it plays in Unity, Unreal or Blender too. Describe a motion in words and the GPU fleet samples one for you. Refine takes a change like make it metallic and generates a new version anchored to the current one, keeping the version history. Optimize runs the platform's web passes on your machine and tells you what it saved. Compare pulls the committed version straight out of git, opens both side by side, and writes a structural review of what changed. Check quality asks a vision model to score the render and hands its fix straight to Refine. A turntable GIF button makes README material in one click. And in HTML, React, Vue, Svelte, Astro and Markdown files the editor now checks agent-3d tags as you type: a missing source or size, an unpinned library script, a stale integrity hash the browser would refuse, a misspelt attribute, each with a one-click fix, plus hovers and completions for every attribute.",
+ "link": "/docs/vscode",
+ "tags": [
+ "feature",
+ "sdk",
+ "improvement"
+ ]
+ },
{
"date": "2026-09-05",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index 75c4a071a..e2d91fb1b 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -6,6 +6,14 @@
<atom:link href="https://three.ws/changelog.xml" rel="self" type="application/rss+xml"/>
<description>What's new on three.ws: features, improvements, and releases, newest first.</description>
<language>en</language>
+ <item>
+ <title>Point an AI agent at the Blender on your own machine</title>
+ <link>https://three.ws/changelog</link>
+ <guid isPermaLink="false">2026-09-07:Point an AI agent at the Blender on your own machine</guid>
+ <pubDate>Mon, 07 Sep 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>A new MCP server drives the Blender you already have installed, with no GUI open and no add-on to install first. An assistant can now read a 3D file and tell you what is actually in it (objects, triangle counts, materials, bones, animations, real-world size), convert between GLB, glTF, FBX, OBJ, STL, PLY, Collada, Alembic, USD and .blend in either direction, render a preview image of a bare asset file that arrives with no camera or lighting of its own, and run a Blender Python script to do the things no single tool covers, like halving a mesh's triangle count and exporting the result in one step. It also reaches back into three.ws: describe something in a sentence and the free text-to-3D lane generates it and opens it in Blender. Blender runs in the background, one process per request, so it works the same on a laptop, a server, or in CI.</description>
+ </item>
<item>
<title>Docs · Pocket Console</title>
<link>https://three.ws/docs/pocket</link>
@@ -126,6 +134,14 @@
<category>fix</category>
<description>The navigation bar was set to stick to the top of the window but never actually did: it scrolled away with the page on every route, at every screen size, so reaching the menu meant scrolling all the way back up. The bar was mounted inside a wrapper exactly its own height, and a sticky element can only travel inside its parent, so it had nowhere to go. The header now stays on screen wherever you scroll, on phones and desktop alike.</description>
</item>
+ <item>
+ <title>The VS Code extension now animates, refines, optimizes and reviews your models, and checks your embeds</title>
+ <link>https://three.ws/docs/vscode</link>
+ <guid isPermaLink="false">2026-09-05:The VS Code extension now animates, refines, optimizes and reviews your models, and checks your embeds</guid>
+ <pubDate>Sat, 05 Sep 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>Open a rigged model in VS Code, press Animate, and pick from the same 2,800-clip motion library the site uses: the clip is retargeted onto that model's own skeleton right in the editor, and Bake clip writes it into a copy of the file so it plays in Unity, Unreal or Blender too. Describe a motion in words and the GPU fleet samples one for you. Refine takes a change like make it metallic and generates a new version anchored to the current one, keeping the version history. Optimize runs the platform's web passes on your machine and tells you what it saved. Compare pulls the committed version straight out of git, opens both side by side, and writes a structural review of what changed. Check quality asks a vision model to score the render and hands its fix straight to Refine. A turntable GIF button makes README material in one click. And in HTML, React, Vue, Svelte, Astro and Markdown files the editor now checks agent-3d tags as you type: a missing source or size, an unpinned library script, a stale integrity hash the browser would refuse, a misspelt attribute, each with a one-click fix, plus hovers and completions for every attribute.</description>
+ </item>
<item>
<title>Walk up to an IRL agent, talk to it out loud, and stand it on your floor in AR</title>
<link>https://three.ws/irl</link>
diff --git a/public/features.json b/public/features.json
index 94bb9e0b2..cfb26f765 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-09-05T16:25:38.038Z",
+ "generated_at": "2026-09-07T00:35:01.146Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
@@ -6378,6 +6378,16 @@
"tags": [],
"showcase": false
},
+ {
+ "path": "/docs/blender-mcp",
+ "title": "Docs · Blender MCP",
+ "description": "Give an AI agent the Blender on your own machine, headless: inspect, convert, render and script 3D files, plus text-to-3D straight into a scene.",
+ "added": null,
+ "auth": null,
+ "indexable": true,
+ "tags": [],
+ "showcase": false
+ },
{
"path": "/docs/spatial-mcp",
"title": "Docs · Spatial MCP",
diff --git a/public/llms-full.txt b/public/llms-full.txt
index 880391c0b..bf2cf9b6e 100644
--- a/public/llms-full.txt
+++ b/public/llms-full.txt
@@ -3856,6 +3856,12 @@ URL: https://three.ws/docs/solana
Give your agent a real on-chain identity on Solana. Your wallet signs one transaction that mints an NFT representing the agent, which is what lets the identity outlive any single platform.
+### Docs · Blender MCP
+
+URL: https://three.ws/docs/blender-mcp
+
+Give an AI agent the Blender on your own machine, headless: inspect, convert, render and script 3D files, plus text-to-3D straight into a scene.
+
### Docs · Spatial MCP
URL: https://three.ws/docs/spatial-mcp
diff --git a/public/llms.txt b/public/llms.txt
index ccf4f9f72..c8d94a7fc 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -679,6 +679,7 @@ Docs, tutorials, and reference.
- [Docs · Sign language, avatars that sign](https://three.ws/docs/sign-language): three.ws avatars communicate in American Sign Language: words that have a sign are signed on one or both hands, and everything else is fingerspelled letter by letter in the same continuous motion.
- [Docs · ERC-8004 smart contracts](https://three.ws/docs/smart-contracts): The three Solidity contracts behind the ERC-8004 identity registry: contract interfaces, deployed addresses, and how to read from and write to each registry from your own code.
- [Docs · Solana agents](https://three.ws/docs/solana): Give your agent a real on-chain identity on Solana. Your wallet signs one transaction that mints an NFT representing the agent, which is what lets the identity outlive any single platform.
+- [Docs · Blender MCP](https://three.ws/docs/blender-mcp): Give an AI agent the Blender on your own machine, headless: inspect, convert, render and script 3D files, plus text-to-3D straight into a scene.
- [Docs · Spatial MCP](https://three.ws/docs/spatial-mcp): An open response shape for returning a live, interactive 3D scene as an MCP tool result instead of a URL in text. A conforming host renders it inline: orbit, animate, and place it in AR. Free to implement, CC0.
- [Docs · Token-gated 3D embeds](https://three.ws/docs/token-gated-3d-embeds): You can already embed a live 3D avatar on any page with one script tag. Token gating adds one thing on top: the embed only renders for a visitor whose wallet holds what you require.
- [Docs · The Trading Copilot](https://three.ws/docs/trading-copilot): The conversational front door to an agent's self-custodied Solana wallet. Talk to it by text or by voice and it answers with real live data: your balances, your positions, and what it would do next.
diff --git a/public/mcp-catalog.json b/public/mcp-catalog.json
index 34daceab6..3392e05fd 100644
--- a/public/mcp-catalog.json
+++ b/public/mcp-catalog.json
@@ -2,15 +2,15 @@
"$comment": "Generated by scripts/build-mcp-catalog.mjs from the tool definitions and price maps in this repo. Do not edit by hand: npm run build:mcp-catalog regenerates it and npm run audit:mcp-catalog fails the build when it is stale.",
"docs": "https://three.ws/docs/mcp-safety",
"counts": {
- "tools": 310,
- "servers": 40,
- "free": 282,
+ "tools": 316,
+ "servers": 41,
+ "free": 288,
"paid": 28,
- "read": 210,
- "write": 76,
- "irreversible": 24,
- "withSchema": 310,
- "withArguments": 286
+ "read": 212,
+ "write": 79,
+ "irreversible": 25,
+ "withSchema": 316,
+ "withArguments": 291
},
"servers": [
{
@@ -93,6 +93,14 @@
"auth": "api-key",
"tools": 5
},
+ {
+ "id": "blender-mcp",
+ "title": "@three-ws/blender-mcp",
+ "endpoint": "npx -y @three-ws/blender-mcp",
+ "transport": "stdio",
+ "auth": "api-key",
+ "tools": 6
+ },
{
"id": "brain-mcp",
"title": "@three-ws/brain-mcp",
@@ -4439,6 +4447,314 @@
},
"source": "packages/billing-mcp/src/tools/query-usage.js"
},
+ {
+ "name": "blender_convert",
+ "title": "Convert a 3D file between formats",
+ "description": "Convert a 3D file from any format Blender can import to any format it can export, driven entirely by the file extensions: .glb, .gltf, .fbx, .obj, .stl, .ply, .dae, .abc, .usd/.usda/.usdc/.usdz, .x3d, and .blend on both sides. Modifiers are applied on export by default, and an optional uniform scale is baked in. Returns the output path, its size, the resulting geometry counts, and the world-space bounds. The input file is never modified; omit \"output\" and the result lands in the server workdir.",
+ "server": {
+ "id": "blender-mcp",
+ "title": "@three-ws/blender-mcp",
+ "endpoint": "npx -y @three-ws/blender-mcp",
+ "transport": "stdio",
+ "auth": "api-key"
+ },
+ "safety": "write",
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": false
+ },
+ "price": {
+ "usd": 0,
+ "free": true
+ },
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "input": {
+ "type": "string",
+ "minLength": 1,
+ "description": "Path to the source 3D file."
+ },
+ "output": {
+ "type": "string",
+ "description": "Destination path. Its extension selects the export format. Defaults to a .glb in the server workdir."
+ },
+ "apply_modifiers": {
+ "type": "boolean",
+ "description": "Apply modifiers (subdivision, decimate, mirror) to the exported geometry. Default true."
+ },
+ "scale": {
+ "type": "number",
+ "exclusiveMinimum": 0,
+ "description": "Uniform scale factor baked into the export, e.g. 0.01 to convert centimetre units to metres."
+ }
+ },
+ "required": [
+ "input"
+ ],
+ "additionalProperties": false
+ },
+ "source": "packages/blender-mcp/src/tools/convert.js"
+ },
+ {
+ "name": "blender_forge_import",
+ "title": "Generate a 3D model with three.ws and open it in Blender",
+ "description": "Generate a 3D model from a text prompt on the public three.ws Forge pipeline, then bring it into Blender. The default image lane (FLUX to TRELLIS) is free and needs no key, wallet, or account. The GLB is saved locally, and if the output path asks for another format (.blend, .fbx, .obj, .usd) Blender converts it on the way in. Returns the local path, the hosted GLB URL, and the geometry counts. Generation runs on a shared GPU lane and typically takes tens of seconds to a couple of minutes. Describe ONE subject per call.",
+ "server": {
+ "id": "blender-mcp",
+ "title": "@three-ws/blender-mcp",
+ "endpoint": "npx -y @three-ws/blender-mcp",
+ "transport": "stdio",
+ "auth": "api-key"
+ },
+ "safety": "write",
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false,
+ "openWorldHint": true
+ },
+ "price": {
+ "usd": 0,
+ "free": true
+ },
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "prompt": {
+ "type": "string",
+ "minLength": 3,
+ "description": "What to generate. One subject, e.g. \"a weathered brass diving helmet\"."
+ },
+ "output": {
+ "type": "string",
+ "description": "Where to save it. The extension picks the format (.glb keeps the original bytes). Defaults to a .glb in the workdir."
+ },
+ "tier": {
+ "type": "string",
+ "enum": [
+ "draft",
+ "standard",
+ "high"
+ ],
+ "description": "Generation quality. Default \"standard\"."
+ },
+ "lane": {
+ "type": "string",
+ "enum": [
+ "image",
+ "geometry",
+ "sketch"
+ ],
+ "description": "Pipeline lane. \"image\" (default) is free. \"geometry\" uses Meshy/Tripo and needs THREE_WS_FORGE_PROVIDER_KEY."
+ },
+ "backend": {
+ "type": "string",
+ "description": "Pin a specific backend. Omit to let the deployment choose for the tier."
+ },
+ "aspect_ratio": {
+ "type": "string",
+ "enum": [
+ "1:1",
+ "4:3",
+ "3:4",
+ "16:9",
+ "9:16"
+ ],
+ "description": "Reference image aspect ratio. Default \"1:1\"."
+ }
+ },
+ "required": [
+ "prompt"
+ ],
+ "additionalProperties": false
+ },
+ "source": "packages/blender-mcp/src/tools/forge-import.js"
+ },
+ {
+ "name": "blender_info",
+ "title": "Inspect the local Blender install",
+ "description": "Report the local Blender this server drives: executable path, version, bundled Python, available render engines, and the import/export formats this build actually supports. Call it first when a tool fails, or to check that Blender is installed at all. Read-only: it opens no file and writes nothing.",
+ "server": {
+ "id": "blender-mcp",
+ "title": "@three-ws/blender-mcp",
+ "endpoint": "npx -y @three-ws/blender-mcp",
+ "transport": "stdio",
+ "auth": "api-key"
+ },
+ "safety": "read",
+ "annotations": {
+ "readOnlyHint": true,
+ "destructiveHint": null,
+ "idempotentHint": true,
+ "openWorldHint": false
+ },
+ "price": {
+ "usd": 0,
+ "free": true
+ },
+ "inputSchema": {
+ "type": "object",
+ "properties": {}
+ },
+ "source": "packages/blender-mcp/src/tools/info.js"
+ },
+ {
+ "name": "blender_render",
+ "title": "Render a preview image of a 3D file",
+ "description": "Render a still PNG of any 3D file Blender can open (.blend, .glb, .fbx, .obj, .usd and the rest). If the scene has no camera, one is created and framed to the model; if it has no light, a key light and a lit world are added, so a bare asset file renders as a usable preview with no setup. A scene that already has its own camera and lighting is rendered as authored. Returns the image path, the engine used, and whether a camera or lights had to be added. Use it to see a model, check a conversion, or produce a thumbnail.",
+ "server": {
+ "id": "blender-mcp",
+ "title": "@three-ws/blender-mcp",
+ "endpoint": "npx -y @three-ws/blender-mcp",
+ "transport": "stdio",
+ "auth": "api-key"
+ },
+ "safety": "write",
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": false
+ },
+ "price": {
+ "usd": 0,
+ "free": true
+ },
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "input": {
+ "type": "string",
+ "minLength": 1,
+ "description": "Path to the 3D file to render."
+ },
+ "output": {
+ "type": "string",
+ "description": "Destination PNG path. Defaults to a .png in the server workdir."
+ },
+ "engine": {
+ "type": "string",
+ "enum": [
+ "auto",
+ "CYCLES",
+ "BLENDER_EEVEE",
+ "BLENDER_WORKBENCH"
+ ],
+ "description": "Render engine. \"auto\" (default) picks CYCLES, which renders on CPU. EEVEE is far faster but needs a GPU context. Call blender_info to see what this build offers."
+ },
+ "samples": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 4096,
+ "description": "Sample count. Default 32: enough for a preview."
+ },
+ "transparent": {
+ "type": "boolean",
+ "description": "Render with a transparent background instead of the world. Default false."
+ }
+ },
+ "required": [
+ "input"
+ ],
+ "additionalProperties": false
+ },
+ "source": "packages/blender-mcp/src/tools/render.js"
+ },
+ {
+ "name": "blender_run_python",
+ "title": "Run a Python script inside Blender",
+ "description": "Execute a Python script inside Blender with the full bpy API available. Optionally open a 3D file first (any format Blender imports) and export the edited scene afterwards, chosen by the output extension. Anything printed is returned as stdout, and assigning a JSON-serializable value to a variable named `result` returns it as structured data. Use this for scene edits the other tools do not cover: decimating meshes, joining or renaming objects, editing armatures, baking animation, cleaning materials. The script runs with the permissions of this server and can read and write the local filesystem.",
+ "server": {
+ "id": "blender-mcp",
+ "title": "@three-ws/blender-mcp",
+ "endpoint": "npx -y @three-ws/blender-mcp",
+ "transport": "stdio",
+ "auth": "api-key"
+ },
+ "safety": "irreversible",
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false,
+ "openWorldHint": false
+ },
+ "price": {
+ "usd": 0,
+ "free": true
+ },
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "string",
+ "minLength": 1,
+ "description": "Python source to execute. `bpy`, `math`, and `Vector` are already imported."
+ },
+ "input": {
+ "type": "string",
+ "description": "3D file to open before running the script. Omit to start from an empty scene."
+ },
+ "output": {
+ "type": "string",
+ "description": "Export the scene here after the script runs; the extension selects the format. Omit to discard it."
+ },
+ "apply_modifiers": {
+ "type": "boolean",
+ "description": "Apply modifiers when exporting. Default true."
+ }
+ },
+ "required": [
+ "code"
+ ],
+ "additionalProperties": false
+ },
+ "source": "packages/blender-mcp/src/tools/run-python.js"
+ },
+ {
+ "name": "blender_scene_info",
+ "title": "Describe a 3D file with Blender",
+ "description": "Open a 3D file with Blender and report what is inside it: object list with types, parents, dimensions and modifiers; evaluated triangle and vertex counts; materials; armature bone names; animation actions with their frame ranges; and world-space bounds. Accepts .blend plus every format this Blender can import (.glb, .gltf, .fbx, .obj, .stl, .ply, .dae, .abc, .usd*, .x3d). Read-only: the file is never modified.",
+ "server": {
+ "id": "blender-mcp",
+ "title": "@three-ws/blender-mcp",
+ "endpoint": "npx -y @three-ws/blender-mcp",
+ "transport": "stdio",
+ "auth": "api-key"
+ },
+ "safety": "read",
+ "annotations": {
+ "readOnlyHint": true,
+ "destructiveHint": null,
+ "idempotentHint": true,
+ "openWorldHint": false
+ },
+ "price": {
+ "usd": 0,
+ "free": true
+ },
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "input": {
+ "type": "string",
+ "minLength": 1,
+ "description": "Path to the 3D file to inspect. Absolute, or relative to the server working directory."
+ },
+ "include_objects": {
+ "type": "boolean",
+ "description": "Include the per-object breakdown. Set false on very large scenes to get totals only. Default true."
+ }
+ },
+ "required": [
+ "input"
+ ],
+ "additionalProperties": false
+ },
+ "source": "packages/blender-mcp/src/tools/scene-info.js"
+ },
{
"name": "chat",
"title": "Run a chat completion",
diff --git a/public/sitemap/index.html b/public/sitemap/index.html
index 36e153e39..cb22a3ae4 100644
--- a/public/sitemap/index.html
+++ b/public/sitemap/index.html
@@ -88,7 +88,7 @@
<main class="sm-wrap">
<div class="sm-hero">
<h1>Sitemap</h1>
- <p>All 913 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p>
+ <p>All 914 pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</p>
<div class="sm-formats">
<a href="/sitemap.xml"><code>sitemap.xml</code> · for search engines</a>
<a href="/llms.txt"><code>llms.txt</code> · for AI agents</a>
@@ -100,7 +100,7 @@
</div>
<div class="sm-filter">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg>
- <input id="sm-filter-input" type="search" placeholder="Filter 913 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
+ <input id="sm-filter-input" type="search" placeholder="Filter 914 pages by name, path, or description…" aria-label="Filter pages" autocomplete="off" spellcheck="false" />
<kbd aria-hidden="true">/</kbd>
</div>
<p class="sm-filter-count" id="sm-filter-count" role="status" aria-live="polite"></p>
@@ -2498,7 +2498,7 @@
<section class="sm-section" id="learn">
<header>
- <h2>Learn<span class="sm-count" data-count>420</span></h2>
+ <h2>Learn<span class="sm-count" data-count>421</span></h2>
<p class="sm-section-desc">Docs, tutorials, and reference.</p>
</header>
<ul class="sm-list">
@@ -4679,6 +4679,13 @@
<span class="sm-desc">Give your agent a real on-chain identity on Solana. Your wallet signs one transaction that mints an NFT representing the agent, which is what lets the identity outlive any single platform.</span>
</a>
</li>
+ <li>
+ <a href="/docs/blender-mcp">
+ <span class="sm-title">Docs · Blender MCP</span>
+ <span class="sm-path">/docs/blender-mcp</span>
+ <span class="sm-desc">Give an AI agent the Blender on your own machine, headless: inspect, convert, render and script 3D files, plus text-to-3D straight into a scene.</span>
+ </a>
+ </li>
<li>
<a href="/docs/spatial-mcp">
<span class="sm-title">Docs · Spatial MCP</span>
diff --git a/scripts/build-mcp-listing-source.mjs b/scripts/build-mcp-listing-source.mjs
index 90563b909..048bd20d3 100644
--- a/scripts/build-mcp-listing-source.mjs
+++ b/scripts/build-mcp-listing-source.mjs
@@ -64,6 +64,16 @@ const OVERLAY = {
"Announce the build result on my open three.ws tab.",
],
},
+ "io.github.nirholas/blender-mcp": {
+ tagline: "Drive the Blender on your own machine: inspect, convert, render and script 3D files, headless.",
+ category: "3d",
+ tags: ["blender", "gltf", "fbx", "usd", "render", "headless", "pipeline"],
+ examplePrompts: [
+ "What is inside this FBX: how many triangles, materials and bones?",
+ "Convert this FBX to a web-ready GLB in metres and render me a preview.",
+ "Halve the triangle count on every mesh and export it as a new GLB.",
+ ],
+ },
"io.github.nirholas/home-mcp": {
tagline: "Read and safely act on a real Home Assistant house: rooms, live state, scenes, gated actions.",
category: "home",
diff --git a/scripts/publish-mcp-servers.mjs b/scripts/publish-mcp-servers.mjs
index eca121a15..09a807fb7 100644
--- a/scripts/publish-mcp-servers.mjs
+++ b/scripts/publish-mcp-servers.mjs
@@ -125,6 +125,7 @@ const SERVERS = [
{ key: 'herald-mcp', dir: 'packages/herald-mcp', manifest: 'packages/herald-mcp/server.json' },
{ key: 'knock-mcp', dir: 'packages/knock-mcp', manifest: 'packages/knock-mcp/server.json' },
{ key: 'home-mcp', dir: 'packages/home-mcp', manifest: 'packages/home-mcp/server.json' },
+ { key: 'blender-mcp', dir: 'packages/blender-mcp', manifest: 'packages/blender-mcp/server.json' },
{ key: 'hood-mcp', dir: 'robinhood/hood-mcp', manifest: 'robinhood/hood-mcp/server.json' },
{ key: 'remote-main', manifest: 'server.json' },
{ key: 'remote-pumpfun', manifest: 'server-pumpfun.json' },
diff --git a/tests/fixtures/mcp-golden-tools.json b/tests/fixtures/mcp-golden-tools.json
index 5b49fef66..2f4f24f18 100644
--- a/tests/fixtures/mcp-golden-tools.json
+++ b/tests/fixtures/mcp-golden-tools.json
@@ -397,6 +397,32 @@
"schemaHash": "9609ea7b118c"
}
],
+ "api/_mcp/tools/library.js": [
+ {
+ "name": "get_catalog_item",
+ "title": "Read one catalog item",
+ "descHead": "FREE, no account or payment. Read one three.ws catalog item in full by i",
+ "descHash": "0aa2b2e399fe",
+ "annotations": "ref:READ_ANNOTATIONS",
+ "schemaHash": "7d00667a7c62"
+ },
+ {
+ "name": "get_item_source",
+ "title": "Get paste-ready source for a catalog item",
+ "descHead": "dynamic",
+ "descHash": "dynamic",
+ "annotations": "ref:READ_ANNOTATIONS",
+ "schemaHash": "0277736ebf5c"
+ },
+ {
+ "name": "search_catalog",
+ "title": "Search the three.ws asset catalog",
+ "descHead": "dynamic",
+ "descHash": "dynamic",
+ "annotations": "ref:READ_ANNOTATIONS",
+ "schemaHash": "f097cbda0f2e"
+ }
+ ],
"api/_mcp/tools/memory.js": [
{
"name": "forget",
@@ -2149,6 +2175,94 @@
"schemaHash": "2a36fb1e6577"
}
],
+ "packages/blender-mcp/src/tools/convert.js": [
+ {
+ "name": "blender_convert",
+ "title": "Convert a 3D file between formats",
+ "descHead": "dynamic",
+ "descHash": "dynamic",
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": false
+ },
+ "schemaHash": "0bcf070dca1a"
+ }
+ ],
+ "packages/blender-mcp/src/tools/forge-import.js": [
+ {
+ "name": "blender_forge_import",
+ "title": "Generate a 3D model with three.ws and open it in Blender",
+ "descHead": "dynamic",
+ "descHash": "dynamic",
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": false,
+ "openWorldHint": true
+ },
+ "schemaHash": "d01f6cc958ef"
+ }
+ ],
+ "packages/blender-mcp/src/tools/info.js": [
+ {
+ "name": "blender_info",
+ "title": "Inspect the local Blender install",
+ "descHead": "dynamic",
+ "descHash": "dynamic",
+ "annotations": {
+ "readOnlyHint": true,
+ "idempotentHint": true,
+ "openWorldHint": false
+ },
+ "schemaHash": "44136fa355b3"
+ }
+ ],
+ "packages/blender-mcp/src/tools/render.js": [
+ {
+ "name": "blender_render",
+ "title": "Render a preview image of a 3D file",
+ "descHead": "dynamic",
+ "descHash": "dynamic",
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": false,
+ "idempotentHint": true,
+ "openWorldHint": false
+ },
+ "schemaHash": "410e05e10d92"
+ }
+ ],
+ "packages/blender-mcp/src/tools/run-python.js": [
+ {
+ "name": "blender_run_python",
+ "title": "Run a Python script inside Blender",
+ "descHead": "dynamic",
+ "descHash": "dynamic",
+ "annotations": {
+ "readOnlyHint": false,
+ "destructiveHint": true,
+ "idempotentHint": false,
+ "openWorldHint": false
+ },
+ "schemaHash": "16cd5146d77d"
+ }
+ ],
+ "packages/blender-mcp/src/tools/scene-info.js": [
+ {
+ "name": "blender_scene_info",
+ "title": "Describe a 3D file with Blender",
+ "descHead": "dynamic",
+ "descHash": "dynamic",
+ "annotations": {
+ "readOnlyHint": true,
+ "idempotentHint": true,
+ "openWorldHint": false
+ },
+ "schemaHash": "0a178135c9d4"
+ }
+ ],
"packages/brain-mcp/src/tools/chat.js": [
{
"name": "chat",