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): return the render inline and stop reporting a busy host as a missing Blender

nirholas3c8439581c89
diff --git a/packages/blender-mcp/src/config.js b/packages/blender-mcp/src/config.js
index c812893f6..1cd9a7629 100644
--- a/packages/blender-mcp/src/config.js
+++ b/packages/blender-mcp/src/config.js
@@ -47,6 +47,20 @@ export const WORKDIR = path.resolve(env('BLENDER_MCP_WORKDIR', path.join(os.tmpd
// unattended deployments and the tool is not advertised at all.
export const ALLOW_PYTHON = boolean('BLENDER_MCP_ALLOW_PYTHON', true);
+// Longest edge of the render copy returned inline in a tool result. A tool
+// result travels through the model's context, so the image that goes back is a
+// scaled copy; the full-resolution PNG is always written to disk.
+export const INLINE_IMAGE_MAX_PX = positiveNumber('BLENDER_MCP_INLINE_IMAGE_PX', 768);
+
+// Hard ceiling on the inlined bytes. Past this the image is left on disk and the
+// response says so, rather than blowing up the caller's context.
+export const INLINE_IMAGE_MAX_BYTES = positiveNumber('BLENDER_MCP_INLINE_IMAGE_BYTES', 1500000);
+
+// How many Blender processes may run at once. Each one costs a few hundred MB,
+// and a parallel agent issuing several calls at once on a small machine pushed
+// the host into spawn failures that surfaced as a bogus "Blender not found".
+export const MAX_CONCURRENCY = positiveNumber('BLENDER_MCP_MAX_CONCURRENCY', 2);
+
// three.ws deployment backing blender_forge_import.
export const THREE_WS_BASE = env('THREE_WS_BASE', 'https://three.ws').replace(/\/+$/, '');
diff --git a/packages/blender-mcp/src/index.js b/packages/blender-mcp/src/index.js
index b2c5e3350..a36636fa5 100644
--- a/packages/blender-mcp/src/index.js
+++ b/packages/blender-mcp/src/index.js
@@ -81,13 +81,19 @@ export function buildServer() {
try {
const result = await tool.handler(args, extra);
const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
- return { content: [{ type: 'text', text }] };
+ // A tool may return extra MCP content blocks alongside its JSON
+ // payload. blender_render uses this to hand back the rendered
+ // image itself, so the caller can SEE the model in the same call
+ // instead of needing filesystem access it may not have.
+ const attachments = tool.attachments ? await tool.attachments(result) : [];
+ return { content: [{ type: 'text', text }, ...attachments] };
} catch (err) {
const payload = {
ok: false,
error: err?.code || 'unhandled',
message: err?.message || String(err),
...(err?.status ? { status: err.status } : {}),
+ ...(err?.diagnostics ? { diagnostics: err.diagnostics } : {}),
...(err?.traceback ? { traceback: err.traceback } : {}),
...(err?.log ? { blender_log: err.log } : {}),
};
diff --git a/packages/blender-mcp/src/lib/blender.js b/packages/blender-mcp/src/lib/blender.js
index 98dde63a9..18f1385f8 100644
--- a/packages/blender-mcp/src/lib/blender.js
+++ b/packages/blender-mcp/src/lib/blender.js
@@ -18,7 +18,7 @@ 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';
+import { BLENDER_PATH, JOB_TIMEOUT_MS, MAX_CONCURRENCY, WORKDIR } from '../config.js';
const HERE = path.dirname(fileURLToPath(import.meta.url));
export const RUNNER_PATH = path.join(HERE, '..', 'py', 'runner.py');
@@ -30,6 +30,7 @@ const MIN_VERSION = [3, 0];
const LOG_TAIL_BYTES = 4000;
let cached = null;
+let inFlight = null;
function candidatePaths() {
const found = [];
@@ -55,29 +56,46 @@ function candidatePaths() {
return found;
}
+/**
+ * Probe one candidate with `--version`.
+ *
+ * Returns `{ version, tuple }` on success, or `{ error }` naming what went
+ * wrong. The distinction matters: a spawn that fails because the host is out of
+ * memory is transient and worth retrying, while a binary that is not Blender
+ * never will be. Collapsing both into "not found" is what turns a busy machine
+ * into a message telling the user to install software they already have.
+ */
function runVersion(binary) {
return new Promise((resolve) => {
let child;
try {
child = spawn(binary, ['--version'], { stdio: ['ignore', 'pipe', 'pipe'] });
- } catch {
- resolve(null);
+ } catch (err) {
+ resolve({ error: `spawn failed: ${err.message}`, transient: true });
return;
}
let out = '';
- const timer = setTimeout(() => child.kill('SIGKILL'), 20000);
+ let timedOut = false;
+ const timer = setTimeout(() => {
+ timedOut = true;
+ child.kill('SIGKILL');
+ }, 20000);
child.stdout.on('data', (chunk) => {
out += chunk;
});
- child.on('error', () => {
+ child.on('error', (err) => {
clearTimeout(timer);
- resolve(null);
+ resolve({ error: `spawn failed: ${err.message}`, transient: true });
});
child.on('close', () => {
clearTimeout(timer);
+ if (timedOut) {
+ resolve({ error: '--version did not answer within 20s', transient: true });
+ return;
+ }
const match = /Blender\s+(\d+)\.(\d+)(?:\.(\d+))?/i.exec(out);
if (!match) {
- resolve(null);
+ resolve({ error: 'ran, but did not identify itself as Blender', transient: false });
return;
}
resolve({
@@ -96,18 +114,29 @@ function runVersion(binary) {
*/
export async function resolveBlender() {
if (cached) return cached;
+ // Parallel tool calls must share one discovery pass. Without this, several
+ // calls each spawn their own `--version` probes at the same moment, which is
+ // exactly the memory pressure that makes probing fail.
+ if (inFlight) return inFlight;
+ inFlight = discoverBlender().finally(() => {
+ inFlight = null;
+ });
+ return inFlight;
+}
- const tried = [];
- for (const candidate of candidatePaths()) {
- if (tried.includes(candidate)) continue;
- tried.push(candidate);
+async function probeCandidates(candidates) {
+ const diagnostics = [];
+ for (const candidate of candidates) {
try {
await access(candidate, constants.X_OK);
} catch {
- continue;
+ continue; // Nothing there: not worth reporting, the list is speculative.
}
const info = await runVersion(candidate);
- if (!info) continue;
+ if (info.error) {
+ diagnostics.push({ path: candidate, problem: info.error, transient: info.transient });
+ 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(
@@ -116,23 +145,55 @@ export async function resolveBlender() {
{ code: 'blender_too_old' },
);
}
- cached = { path: candidate, version: info.version, tuple: info.tuple };
+ return { found: { path: candidate, version: info.version, tuple: info.tuple }, diagnostics };
+ }
+ return { found: null, diagnostics };
+}
+
+async function discoverBlender() {
+ const candidates = [...new Set(candidatePaths())];
+ let { found, diagnostics } = await probeCandidates(candidates);
+
+ // A Blender that exists but would not answer is a transient condition on a
+ // loaded machine, not a missing install. Give it one more chance before
+ // telling anyone their setup is wrong.
+ if (!found && diagnostics.some((entry) => entry.transient)) {
+ await new Promise((resolve) => setTimeout(resolve, 750));
+ const retry = await probeCandidates(diagnostics.filter((entry) => entry.transient).map((entry) => entry.path));
+ if (retry.found) found = retry.found;
+ else diagnostics = [...diagnostics, ...retry.diagnostics];
+ }
+
+ if (found) {
+ cached = found;
return cached;
}
+ if (diagnostics.length > 0) {
+ throw Object.assign(
+ new Error(
+ `Blender is installed at ${diagnostics[0].path} but could not be run: ${diagnostics[0].problem}. ` +
+ 'On a loaded machine this is usually transient (retry the call); otherwise check that the executable ' +
+ 'works by running it yourself, or point BLENDER_PATH at a different one.',
+ ),
+ { code: 'blender_unusable', diagnostics },
+ );
+ }
+
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) },
+ { code: 'blender_not_found', tried: candidates.slice(0, 12) },
);
}
/** Reset the cached executable. Tests use this; nothing else needs it. */
export function resetBlenderCache() {
cached = null;
+ inFlight = null;
}
function tail(text) {
@@ -146,6 +207,27 @@ export async function ensureWorkdir() {
return WORKDIR;
}
+// Blender costs a few hundred MB per process, so unbounded parallelism on a
+// small machine turns into spawn failures rather than throughput. Calls queue
+// instead of competing.
+let running = 0;
+const waiting = [];
+
+async function acquireSlot() {
+ if (running < MAX_CONCURRENCY) {
+ running += 1;
+ return;
+ }
+ await new Promise((resolve) => waiting.push(resolve));
+ running += 1;
+}
+
+function releaseSlot() {
+ running -= 1;
+ const next = waiting.shift();
+ if (next) next();
+}
+
/**
* Run one job through the in-Blender runner and return its payload.
*
@@ -158,6 +240,7 @@ export async function ensureWorkdir() {
export async function runJob(job, { timeoutMs } = {}) {
const blender = await resolveBlender();
await ensureWorkdir();
+ await acquireSlot();
const dir = await mkdtemp(path.join(WORKDIR, 'job-'));
const jobPath = path.join(dir, 'job.json');
const resultPath = path.join(dir, 'result.json');
@@ -224,6 +307,7 @@ export async function runJob(job, { timeoutMs } = {}) {
}
return { ...payload, blender_path: blender.path };
} finally {
+ releaseSlot();
await rm(dir, { recursive: true, force: true });
}
}
diff --git a/packages/blender-mcp/src/tools/render.js b/packages/blender-mcp/src/tools/render.js
index 67ee346de..7b6cccf3b 100644
--- a/packages/blender-mcp/src/tools/render.js
+++ b/packages/blender-mcp/src/tools/render.js
@@ -9,9 +9,12 @@
// 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 { readFile, rm } from 'node:fs/promises';
+
import { z } from 'zod';
import { runJob } from '../lib/blender.js';
+import { INLINE_IMAGE_MAX_PX, INLINE_IMAGE_MAX_BYTES } from '../config.js';
import { resolveInput, resolveOutput } from '../lib/paths.js';
export const def = {
@@ -22,8 +25,9 @@ export const def = {
'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.',
+ 'its own camera and lighting is rendered as authored. The rendered image is returned INLINE alongside the ' +
+ 'JSON, so you can actually look at the model in this one call without needing filesystem access, while the ' +
+ 'full-resolution PNG is written to disk. 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.'),
@@ -41,6 +45,10 @@ export const def = {
.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.'),
+ inline_image: z
+ .boolean()
+ .optional()
+ .describe('Return the image inline so you can see it, downscaled to fit the context. Default true.'),
},
async handler(args) {
const input = await resolveInput(args?.input);
@@ -53,7 +61,31 @@ export const def = {
samples: args?.samples ?? 32,
resolution: args?.resolution ?? [960, 960],
transparent: args?.transparent === true,
+ inline_max_px: args?.inline_image === false ? 0 : INLINE_IMAGE_MAX_PX,
});
- return { ...payload, ok: true };
+ return { ...payload, ok: true, inline_image: args?.inline_image !== false };
+ },
+
+ /**
+ * Hand the rendered image back as an MCP image block.
+ *
+ * The scaled copy is read and then deleted: it exists only to travel in this
+ * response, and leaving it beside the real output would be litter the caller
+ * has to reason about. An image too large to inline is reported in the JSON
+ * rather than silently dropped, so the caller knows to read the file.
+ */
+ async attachments(result) {
+ if (!result?.inline_image) return [];
+ const path = result.preview || result.output;
+ const bytes = result.preview ? result.preview_bytes : result.output_bytes;
+ if (!path || !bytes) return [];
+ if (bytes > INLINE_IMAGE_MAX_BYTES) {
+ result.inline_image_skipped = `the image is ${bytes} bytes, over the ${INLINE_IMAGE_MAX_BYTES} inline limit; read it from ${result.output}`;
+ if (result.preview) await rm(path, { force: true });
+ return [];
+ }
+ const data = await readFile(path);
+ if (result.preview) await rm(path, { force: true });
+ return [{ type: 'image', data: data.toString('base64'), mimeType: 'image/png' }];
},
};