npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

xelta-blender-mcp

v0.2.0

Published

Local MCP server that lets Claude drive Blender for Xelta through a background Blender process.

Readme

Xelta for Blender (xelta-blender-mcp)

The local half of Xelta for Blender: an MCP server that runs on your computer and lets Claude work with Blender.

It starts its own Blender in the background (no window) on the first call that needs it, keeps it running for the calls after it, and talks to it over pipes. It reports the Blender install, describes the scene, and builds a product-shot scene: an empty scene, the product (a primitive or your own model), its material and brand label, a seamless studio backdrop and background, a camera framed on it, studio lights, and a saved .blend. It shows Claude a quick preview of the camera's view, and renders final PNG/JPG stills and MP4 turntables as background jobs.

macOS / Windows / Linux · Node.js 24+ · Blender 4.2+

Install

npm install -g xelta-blender-mcp
xelta-blender doctor
xelta-blender config

config prints the mcpServers entry and the exact claude mcp add --scope user xelta-blender … line, with absolute paths to this install. Run that line to register the server with Claude Code. If BLENDER_EXECUTABLE is set when you run config, it is carried into the registration.

Commands

| Command | What it does | | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | xelta-blender | Starts the stdio MCP server (what MCP clients run). | | xelta-blender doctor | JSON installation checks: Node version, package files, a writable runtime dir, where Blender is, and that it is 4.2 or newer. Exits 1 when a check fails. | | xelta-blender config | Prints the client registration. | | xelta-blender probe scene [--out <dir>] | Builds a scene from the bundled model in a background Blender (import Product, Floor, a framed Camera, a three-light rig), saves it, reopens it and checks the readback against what was built. Writes only into a new folder (default <tmp>/xelta-blender/probe-scene-<stamp>). Prints a JSON report; exits 0 when every step passes, 1 otherwise, 2 on bad arguments. | | xelta-blender probe look [--out <dir>] | The same with the studio look: a glossy red Product material, the bundled fixtures/label.png wrapped around the bottle, a Backdrop and a dark world instead of the floor, then camera and rig. After reopening it checks the material values, the packed label, the backdrop and the world. Default folder <tmp>/xelta-blender/probe-look-<stamp>; same report and exit codes. | | xelta-blender probe render [--out <dir>] | Builds the look scene at 640×800 and saves it, takes a preview (at most 512 px), renders a still as a job and checks its exposure (mean luminance 0.2–0.8) and the product's hue (still red, not pink), renders a 24-frame turntable MP4 as a job polled to done and counts its frames, and checks the scene got no keyframes. Writes probe-render.blend, preview.png, still.png and turntable.mp4 into a new folder (default <tmp>/xelta-blender/probe-render-<stamp>); same report and exit codes. | | xelta-blender probe destruction [--trigger <kind>\|--all-triggers] [--no-dust] [--no-video] [--out <dir>] | Builds a passive Ground, shatters a 4×0.3×2.5 m Wall into 40 pieces, makes them rigid and asleep, glues them with breakable joints anchored to the ground, adds a trigger at frame 30 (wrecking_ball by default; --trigger picks projectile, explosion, falling_object or timed_break, and --all-triggers runs one fresh wall per kind), 150 debris rocks and dust (smoke.add), bakes the simulation into probe-destruction-<kind>.blend as a job, and checks the reopened bake: no piece moved more than 1 cm by frame 28, at least 5 pieces moved by the end, and the debris landed (most below 0.5 m, none below −0.1 m). Then the dust: none at frame 28, some at frame 36, its cache folder probe-destruction-<kind>_cache beside the .blend, and a copy of both (in copy-<kind>/) opened in a fresh Blender reads the same dust at frame 36 (within 1%). --no-dust leaves the dust out. Then the shot: the plain camera gives way to camera.action (its defaults), and a preview MP4 (preview-<kind>.mp4, 25%, 8 samples) and a contact sheet (contact-sheet-<kind>.png of frames 27, 28 and 50, three 320 px tiles) are rendered as jobs and checked: the MP4 has the scene's 120 frames, the sheet is 960 px wide, and the two tiles before the impact (the camera still) differ less than half as much as the two across it. --no-video skips them. The JSON report adds triggers with each kind's result. Default folder <tmp>/xelta-blender/probe-destruction-<stamp>; same report and exit codes. | | xelta-blender probe video [--out <dir>] | Sets the timeline to 1–48 at 24 fps, keys a cube sliding from x −2 to x 2 over it (object.animate, linear) and checks its readback shows the keys at 1 and 48, adds a sun and a camera at 640×360 and 16 samples, checks with shot.check that the cube is in frame at frames 1, 24 and 48 and its screen box moves right, renders the scene's range as a final MP4 with render.video (a job polled to done), and checks the movie has 48 frames at 24 fps and 640×360, exports the scene with scene.export_glb and checks the .glb holds at least one mesh and one animation, and checks the scene keeps its timeline and keys. Writes probe-video.mp4 and probe-video.glb into a new folder (default <tmp>/xelta-blender/probe-video-<stamp>); same report and exit codes. |

Tools

| Tool | What it does | | ------------------ | ---------------------------------------------------------------------------------------------------------------- | | bl_status | Whether Blender is installed, its path and version, and whether the background process runs. Never starts it. | | bl_scene_summary | The background Blender's scene: file, frame range, fps, units, render settings and every object. | | bl_catalog | The operations bl_do can run, with JSON-Schema params. | | bl_do | Runs one operation by name. | | bl_get_skill | The bundled Xelta skills, offline. | | bl_preview | A quick low-sample Cycles PNG of the active camera's view (longest side 512 by default), as image content. | | bl_job_status | A render job's state and progress, or every job of this server session, newest first. Never starts Blender. | | bl_job_cancel | Stops a queued or running render job; nothing is written at its path. | | bl_python | Runs a Python script in the background Blender, only with confirm: true after your yes. Not a sandbox (below). |

bl_python is not a sandbox

bl_python { script, confirm: true, write_roots?, timeout_s? } is an escape hatch for one-off effects the typed operations do not have. It runs the script inside the bridge's own background Blender (never your open one), and only with confirm: true, which Claude must pass only after you said yes to that script. While the script runs, a guard refuses writes outside write_roots (absolute folders you approved) and the bridge's runtime dir, and the common process-launch and network routes (subprocess, os.system, ctypes, connects and DNS lookups beyond loopback): GUARD_BLOCKED. Reads are never guarded, so importing a model or opening a .blend from any folder works; reopening a file over unsaved changes is UNSAVED_CHANGES, and saving or opening a .blend a bake job is writing is BAKE_IN_PROGRESS. Threads a script leaves running are reported (THREADS_LEFT_RUNNING) and end with a restart of the background Blender; bpy.app.handlers it adds are removed (HANDLERS_REMOVED). Its prints, and anything written to the process's stdout or stderr meanwhile, are captured and never reach the protocol. The guard is best effort and not a sandbox: it is a Python audit hook plus a check of the paths that Blender's writing operators (saves, exports, image saves, unpacking, cache bakes, renders) will write to, and Blender's own C code writes without raising audit events. Known gaps: datablock methods such as Image.save() and save_render(), bpy.data.libraries.write(), the real bpy reached through sys.modules, importlib or builtins.__import__, compositor file outputs, operators the guard does not list, timers and msgbus subscriptions, and C-level exporters called by other routes. A script can read any file your account can, and can change or wreck the scene. Every result says guard: "best-effort". Only say yes to a script you would run yourself.

Operations

bl_do runs these (units: metres, degrees and kilograms; objects by exact name). Every write returns the scene.summary readback (renders and bakes return their job).

| Operation | What it does | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | app.info, scene.summary | Blender version and engines; the scene, its active camera, unsaved changes, and every object (cameras and lights with their settings). | | scene.new, scene.open, scene.save | An empty metric scene (1-120 at 30 fps); open or save a .blend. No silent loss: UNSAVED_CHANGES without discard: true, FILE_EXISTS without overwrite: true. | | object.add_primitive, object.import | A cube, plane, cylinder, cone, sphere, ico_sphere or torus; or a .glb/.gltf/.obj/.fbx/.stl/.usd* model grouped under one named empty, fitted to a size and stood on the floor. | | object.transform, object.delete | Move, rotate or scale an object; delete it with its children. | | scene.timeline | The scene's frame range and fps (before physics.rigid and smoke.add, whose caches are sized to the range). | | scene.export_glb | The scene, or named objects and their children, as one .glb for web viewers, game engines and AR, keyed animation included unless animation: false. The scene is not changed. Reports the file's node, mesh and animation counts and what glTF drops (area lights, volumes and smoke, physics, procedural materials). FILE_EXISTS without overwrite: true. | | object.animate | Keys on an object's location, rotation and scale at given frames, bezier, linear or constant, optionally cycled; replace or merge. The readback shows each object's keyed frames and channels. | | camera.add | A scene camera that frames an object's bounding sphere from an azimuth and elevation, or sits at a location looking at a point. | | light.add, light.studio_rig | One point, sun, spot or area light; or a key, fill and rim area-light rig sized to the target. | | material.set, material.label | One Principled material on an object or every mesh of an import (colour, metallic, roughness, IOR, alpha, transmission, emission, coat); a .png/.jpg label over it, tube or flat, packed into the .blend. | | studio.backdrop, world.set | A matte seamless backdrop (a floor curving into a back wall) sized to the scene; the world's background colour and strength. | | render.settings | Engine (cycles, or eevee with a fall-back to Cycles), samples, resolution, transparent background and denoise. | | render.still, render.turntable | A PNG/JPG still, or an H.264 MP4 of the product turning a full circle as a seamless loop, rendered as a job in a separate Blender from a copy of the scene. FILE_EXISTS without overwrite: true. | | fracture.voronoi | Shatters a mesh into 2–500 convex Voronoi pieces (seeded, denser near a focus point; cut faces can take an inner material) in a <object> pieces collection; the original is kept, hidden. | | physics.rigid, physics.breakable_joints | Active or passive rigid bodies (mass split by volume, friction, bounciness, asleep until hit); breakable fixed joints between touching pieces, the bottom ones anchored to the ground. | | physics.trigger | What breaks the pieces, at a chosen frame: a wrecking ball swinging on a cable, a projectile, an explosion (a force field keyed on for two frames), a falling box, or a timed break that switches every joint off. The objects go in <pieces> triggers. | | debris.emit | Up to 1000 small rigid rocks, parked out of sight and out of collisions until the break, then thrown out of it to fall and land (seeded); a SLOW_BAKE warning above 400. | | smoke.add | Dust (or smoke) from the break: a gas domain around the pieces, a plume from the ground under them and trails from the largest debris rocks, all switched on at the trigger's frame; a NO_DEBRIS warning when there are no rocks to trail it. | | sim.bake | Saves the scene, bakes the rigid-body simulation into that .blend in a separate Blender (a job), then any dust or smoke into a <blend name>_cache folder beside it, then reopens it so previews and renders show the motion. BAKE_NOT_LOADED if the scene changed meanwhile. | | smoke.stats | How much baked dust there is at chosen frames (the density summed over the domain, and its densest cell), to check its timing. | | camera.action | A camera for the destruction shot: it tracks an empty at the impact, frames the whole target, holds still until the hit, then pushes in toward it by the end and shakes briefly (seeded, decaying) on the hit. | | render.preview_video, render.contact_sheet | Quick reviews of the whole shot as jobs: a low-sample H.264 MP4 of every frame (EEVEE by default, at a share of the resolution, dust included), or chosen frames (default six around the impact) in one PNG grid on #111111. Not final renders. | | render.video | The final video of the shot as a job: an H.264 MP4 of the scene's frame range (or a sub-range within it) from the active camera, with the engine, samples and resolution of render.settings (no sample cap), at a share of the resolution (default 100%). Once done, job.result is {frames, fps, duration_s, width, height}. | | shot.check | A numeric check of a moving shot, without changing it: at chosen frames (default the start, ¼, ½, ¾ and the end), each object's screen box from the active camera and whether it is in frame, partly, out or behind the camera, plus exposure stats (mean luminance, clipped and near-black shares, a 3×3 grid) from a tiny Cycles render of about a second per frame. Numbers only, no verdict. |

The readback lists every material in use (materials), the world, the render settings and a physics block (the rigid-body world and whether it is baked, each pieces collection with its rigid bodies, joints and debris, the triggers, the dust and smoke domains with their cache folders, and once baked how many pieces moved, whether any moved before its trigger and where the debris landed). The dust's cache folder sits beside the .blend and is found relatively, so move or copy the two together; scene.save to another file copies it along. No fire, flames or liquids; no HDRI, free node editing, compositing, render passes or EXR. See docs/TOOLS.md for the generated reference, and docs/operations.json for the same tools and operations (with JSON-Schema params) as machine-readable JSON.

Skills

bl_get_skill serves four bundled skills, offline:

| Skill | What it covers | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | xelta-bl-editing-rules | Load first. Start-up, the background-process model, inspect then one change then readback, exact names, safety, errors, preview before render, shot.check, jobs, the MP4-by-default rule with a render-time estimate, and an op cookbook. | | xelta-bl-product-shot | Studio product shots: brief, scene, product, camera, studio rig, look, preview, a still and a turntable by default, the saved .blend and an optional .glb, with lighting and render recipes. | | xelta-bl-destruction | Destruction shots: brief, ground, the object, fracture, rigid bodies, joints, a trigger, debris, dust or smoke, an action camera, the bake and its checks, contact sheet, preview video and shot.check, the final render.video MP4, with trigger and strength guidance and four worked shots. | | xelta-bl-scene-building | Animated scenes from a prompt, or "take it by yourself": a scene plan, role names (HERO_, ENV_, PRP_, CAM_, LGT_), the camera and a working light first, a blockout through ordered checks, motion with scene.timeline and object.animate, a motion audit with a contact sheet and shot.check, the final render.video MP4, the .blend and an optional .glb, with a plan-and-checks reference and the boy-to-bus scene as a worked example. |

Every delivery ends with an MP4 (render.video for a shot with motion, render.turntable for a still product) unless the user declines it, and the agent then reports why there is none; a test holds each task skill to that.

Each skill ends with what the bridge cannot do: it cannot see or edit the Blender you have open, has no add-on, socket or live viewport, physics only as destruction (fracture, rigid bodies, breakable joints, triggers, rigid debris, dust and smoke, a baked simulation, an action camera with a preview video and contact sheet; no fire, flames or liquids), animation only as keyed objects (object.animate, scene.timeline; no armatures, bones, character rigs or shape keys), a .glb that drops area lights, volumes, physics and procedural looks, no geometry nodes or sculpting, no HDRI or environment maps, no compositing, render passes or EXR; EEVEE may fall back to Cycles, and transparent backgrounds come only in PNG stills.

How it runs Blender

The server runs blender -b --factory-startup --python blender-scripts/xelta_bridge.py once, on the first live call, and sends it one JSON request per line. The bridge answers with lines tagged @@XELTA@@ ; everything else Blender prints is logged to the server's stderr.

  • It only touches the files you name: the .blend given to scene.save / scene.open (no .blend1 backup), the .glb given to scene.export_glb, the model given to object.import, the image given to material.label (read and packed into the scene), the still, video or sheet given to render.still / render.turntable / render.preview_video / render.video / render.contact_sheet, and the .blend given to sim.bake (saved, then baked in place by a job Blender; never deleted or moved). Previews, shot.check's tiny renders and job copies live in its runtime dir and are deleted. A bl_python script you agreed to is the exception: it can write inside the folders you approved, and its guard is best effort (above).
  • It never touches your open Blender. There is no add-on, socket or open port. The bridge cannot see a Blender you have open, or a scene you have not saved; it works in its own process, which starts with the factory scene (Cube, Light, Camera).
  • One request at a time, each with a timeout (BLENDER_MCP_TIMEOUT_MS).
  • Restarts lose the scene. A request that times out kills the process, since a hung Python call inside Blender cannot be interrupted. A process that exits mid-request fails that request. The next call starts a fresh Blender, and its reply carries a PROCESS_RESTARTED warning.
  • Renders run as jobs. render.still, render.turntable, render.preview_video, render.video and render.contact_sheet have the scene process save a copy of the scene into the runtime dir (<tmp>/xelta-blender/runtime/jobs), then a second blender -b <copy> --python blender-scripts/xelta_job.py renders it, so the scene process keeps answering and later edits never change a running render. One job runs at a time; the others queue. Progress comes from Blender's render handlers as tagged lines, never from its log text. The job renders into its own folder and the file is moved to your path when it is done, so a cancelled or failed job leaves nothing there; a finished job's copy is deleted. When EEVEE cannot render in the background, the job renders with Cycles and reports ENGINE_FALLBACK. The copy sits away from your .blend, so the job points each dust or smoke domain at its real cache folder (an absolute path) before rendering, and baked dust shows.
  • Previews are quick. bl_preview renders a small, low-sample Cycles image in the scene process and restores the render settings afterwards.
  • No orphans. The background Blender and any job Blender are killed when the server exits (and job copies removed); both quit by themselves if the server's pipes close.

Environment variables

| Variable | Meaning | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | BLENDER_EXECUTABLE | Path to the Blender executable (macOS: /Applications/Blender.app/Contents/MacOS/Blender; Windows: …\blender.exe). When set it must exist; there is no fallback. Without it, the default install is used. | | BLENDER_MCP_TIMEOUT_MS | Request timeout in ms. Default 60000, clamped to 1000–1800000. | | LOG_LEVEL | Log level on stderr: 0 debug, 1 info (default; includes Blender's own output), 2 warn, 3 error. |

Without BLENDER_EXECUTABLE, Blender is looked for at /Applications/Blender.app then ~/Applications/Blender.app (macOS), the newest %ProgramFiles%\Blender Foundation\Blender <x.y>\blender.exe (Windows), or blender on PATH, /usr/bin/blender and /snap/bin/blender (Linux).

Errors

Every failure has one shape:

{
  "ok": false,
  "error": {
    "code": "BLENDER_NOT_FOUND",
    "message": "Blender was not found …",
    "retryable": false,
    "hint": "Install Blender 4.2 or newer, or set BLENDER_EXECUTABLE …"
  }
}

| Code | Meaning | Retryable | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | | BLENDER_NOT_FOUND | No Blender found, or BLENDER_EXECUTABLE points nowhere. | no | | BLENDER_TOO_OLD | The Blender found is older than 4.2. | no | | PROCESS_START_FAILED | Blender could not start, or printed no ready line within 60 s. Carries its last output. | no | | PROCESS_RESTARTED | A warning next to a result: the call ran in a fresh Blender, so earlier scene state is gone. | no | | TIMEOUT | The request ran past its timeout; Blender was stopped. | yes | | TRANSPORT | Blender exited mid-request, or another pipe failure. | yes | | PYTHON_ERROR | The operation raised inside Blender; carries the last 20 traceback lines. | no | | UNKNOWN_OPERATION | No operation with that name. | no | | INVALID_ARGS | The params failed the operation's schema; Blender was not started. | no | | OBJECT_NOT_FOUND | No object with that exact name in the scene. | no | | NAME_TAKEN | A new object's name is already used (Blender is never allowed to append .001). | no | | FILE_EXISTS | scene.save, scene.export_glb or a render would replace a file (or a dust cache folder); pass overwrite: true only if agreed. | no | | FILE_NOT_FOUND | The file to open, import or use as a label (or the folder to save into) does not exist. | no | | UNSAVED_CHANGES | scene.new / scene.open would drop unsaved changes; pass discard: true only if agreed. | no | | UNSUPPORTED_FORMAT | object.import cannot read that file type; checked before Blender starts. | no | | NO_CAMERA | A preview or render needs an active camera and the scene has none. | no | | JOB_NOT_FOUND | No render job with that id in this server session. | no | | RENDER_FAILED | A render job's Blender failed; carries the job's last 20 log lines. | no | | BAKE_FAILED | A sim.bake job's Blender failed; carries the job's last 20 log lines. | no | | ENGINE_FALLBACK | A warning next to a result: EEVEE could not render in the background, so Cycles did. | no | | TRANSPARENCY_IGNORED | A warning on a JPG or MP4 job: it has no alpha, so it rendered with the scene's background. | no | | BAKE_IN_PROGRESS | scene.save, scene.open or sim.bake on a .blend a bake job is still writing (and bl_python while one bakes the scene's own file). | no | | BAKE_NOT_LOADED | A warning on sim.bake: the scene changed while it baked, so the baked file was not reopened. | no | | SLOW_BAKE | A warning on debris.emit: more than 400 rocks make sim.bake noticeably slower. | no | | GUARD_BLOCKED | bl_python's best-effort guard refused a write outside the approved folders, or a common process-launch or network route; details.blocked names it. | no | | THREADS_LEFT_RUNNING | A warning on bl_python: the script left threads running, so the background Blender was restarted after the reply. | no | | HANDLERS_REMOVED | A warning on bl_python: bpy.app.handlers the script added were removed. | no | | NO_DEBRIS | A warning on smoke.add: the pieces have no debris, so the dust has no trails. | no | | UNBAKED_SIMULATION | A warning on shot.check: a rigid-body world or smoke domain is not baked, so every frame shows the start pose; sim.bake first. | no |

Licence

This package is (MIT AND GPL-3.0-or-later):

The Node code never imports the Python: it starts Blender as a separate program and passes it the script's path. See THIRD_PARTY_NOTICES.md.