design-os-3d-blender
This MCP server lets an agent inspect Blender availability, query bpy 5.2 knowledge, validate part specs, and run headless Blender scripts with an AGENT_OK / AGENT_FAIL result.
Check the host environment and whether a Blender 5.2 binary and knowledge base are ready.
Search the verified bpy 5.2 knowledge base for modeling, shading, modifiers, and gate rules.
Validate a
spec.jsonfor millimeter units, target dimensions, tolerance, and minimum wall.Execute bpy Python scripts in headless Blender, optionally opening a
.blendfile, and verify the sentinel contract.Support agent-driven mechanical-part modeling, rendering, checks, and STL/glTF export workflows.
Provides a headless Blender Python (bpy) pipeline for generating parametric mechanical parts, rendering and verifying geometry, and exporting production-ready 3D assets such as glTF and STL.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@design-os-3d-blender Generate a 24-tooth helical gear and export STL + glTF."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
DESIGN:OS 3D Blender
An MCP server and agent skill for Blender 5.2. Your coding agent models, renders and checks mechanical parts on your machine: four tools, an AGENT_OK contract, and a 3D-print production gate. Specs are locked to millimeters. Exports are STL and glTF.
FREE + source-available (PolyForm Shield 1.0.0).
Quickstart
In Claude Code:
/plugin marketplace add jangtrinh/design-os-3d-blender
/plugin install design-os-3d-blender@design-os-3d-blenderFrom a clone (Codex, Gemini CLI, Antigravity, Cursor, or a standalone MCP client):
git clone https://github.com/jangtrinh/design-os-3d-blender.git
cd design-os-3d-blender
python3 scripts/self_check.py
pip install .Point your MCP client at the installed command, and set BLENDER_BIN to your Blender 5.2 binary:
{
"mcpServers": {
"design-os-3d-blender": {
"command": "design-os-3d-blender",
"env": {
"BLENDER_BIN": "/Applications/Blender.app/Contents/MacOS/Blender"
}
}
}
}On Linux the binary is often /usr/bin/blender. The first tool will tell you if it cannot find it. If you use uv, uv run design-os-3d-blender from this repository starts the same server, with no need to publish a package.
Ask for a part in plain English. A typical pass validates a spec.json, runs a headless bpy script, and stops on one line: AGENT_OK or AGENT_FAIL.
Related MCP server: cad-3d-builder
What it makes
These are real builds from this repository, made in Blender 5.2 through the agent pipeline.
Build | What it is | In this repo |
CK-001 | A compact keyboard, from photo and spec to a printable kit | |
DC-01 | A desk robot: printed parts, a carrier board, an assembly film | |
Robot arm | A printable arm, with gated plates | |
Nodestack | Modular industrial storage |
DC-01 assembled, and the printable robot arm open in a real Blender 5.2 window. Print plates for the arm are in docs/images/readme/builds/print-plates.jpg and docs/media/robot-arm-print-plates.png.
How it works
The MCP server exposes four tools. That is the count in src/design_os_3d_blender_mcp/server.py on this branch:
Tool | What it does |
| Host, Python, and whether a Blender 5.2 binary is on the path. Call this first. |
| Search the verified bpy 5.2 knowledge base in |
| Check a |
| Run a headless pass and read the |
Two prompts (design_parametric_part, review_geometry_gate) and two resources (blender://knowledge/index, blender://specs/bracket-example) sit next to the tools. They are not extra tools.
Every executed pass ends with one machine-readable line. Exit codes alone are not a verdict. The 3D-print production gate checks manifold geometry, wall thickness and millimeter-locked bounds. Worked specs live in specs/ and builds/.
The Claude Code, Codex and other agent plugins install the same skill, skills/design-os-3d-blender/SKILL.md. /doctor is a read-only diagnostic. python3 scripts/self_check.py is the offline repository check: it prints ok: design-os-3d-blender self-check passed (design-os-3d-blender) and exits 0 when the manifests and contracts match.
Nothing in the server sends data off your machine. See PRIVACY.md.
Install
Choose the setup that matches your agent. Every option uses the same skill at skills/design-os-3d-blender/SKILL.md.
Claude Code
/plugin marketplace add jangtrinh/design-os-3d-blender
/plugin install design-os-3d-blender@design-os-3d-blenderOpenAI Codex
git clone https://github.com/jangtrinh/design-os-3d-blender.git /tmp/design-os-3d-blender
mkdir -p ~/.codex/skills/design-os-3d-blender ~/.codex/prompts
cp -R /tmp/design-os-3d-blender/skills/design-os-3d-blender/* ~/.codex/skills/design-os-3d-blender/
cp /tmp/design-os-3d-blender/prompts/doctor.md ~/.codex/prompts/design-os-3d-blender-doctor.md
rm -rf /tmp/design-os-3d-blenderGemini CLI and Google Antigravity
git clone https://github.com/jangtrinh/design-os-3d-blender.git /tmp/design-os-3d-blender
mkdir -p ~/.gemini/skills/design-os-3d-blender
cp -R /tmp/design-os-3d-blender/skills/design-os-3d-blender/* ~/.gemini/skills/design-os-3d-blender/
rm -rf /tmp/design-os-3d-blenderOpenCode, Cursor, Windsurf and other agent harnesses
git clone https://github.com/jangtrinh/design-os-3d-blender.git /tmp/design-os-3d-blender
mkdir -p ~/.agents/skills/design-os-3d-blender
cp -R /tmp/design-os-3d-blender/skills/design-os-3d-blender/* ~/.agents/skills/design-os-3d-blender/
rm -rf /tmp/design-os-3d-blenderVerify:
python3 scripts/self_check.pyOr run /doctor inside Claude Code or Codex to inspect installed skill paths, plugin manifests, and whether Blender is reachable.
Uninstall the skill copies:
rm -rf ~/.claude/skills/design-os-3d-blender ~/.codex/skills/design-os-3d-blender ~/.gemini/skills/design-os-3d-blender ~/.agents/skills/design-os-3d-blenderPrompt recipes live in docs/cookbook.md. More setup notes are in docs/antigravity-setup.md and docs/upstream-agent-integration.md.
Limits
Sheet-metal or paperboard folding, where 2D crease patterns govern the topology: use
design-os-origami.Organic character sculpting or a full game-character rig that needs a sculptor's pass.
2D vector UI motion: use
design-os-svg-animation.
Watch
A FREE, source-available (PolyForm Shield) agent pipeline for Blender 5.2. Videos from the design:os by Jang channel (Vietnamese, with English terms):
How to use design os 3d blender repo - ep 1 (2:57). Episode 1: building a keyboard (CK-001) end to end: photo, spec, gates, STL and GLB export. Vietnamese.
How to use design os 3d blender repo - ep 2 (5:34). Episode 2: the DC-01 desk robot with 29 mechanical revisions, four gated runs and a printable kit. Vietnamese.
Fanmade 3D model for Nowa planet - by design os 3d blender (0:27). A 27-second fan-made 3D model of the Nowa desktop product, built with design-os-3d-blender.
More: design:os by Jang on YouTube.
DESIGN:OS
This is one of the DESIGN:OS tools. The others: Studio, CLI, Bridge, SVG Animation, Code2Flow, Knowledge Builder and more on jangtrinh.github.io.
Engine | Live docs | Repository |
DESIGN:OS CLI | ||
Knowledge Builder | ||
DESIGN:OS Bridge | ||
SVG Animation Engine | ||
3D Blender | ||
OPAH ONE Drone | ||
GitHub Pages Engine | ||
Apple Design OS | ||
Agent Teacher | ||
Origami CAD | ||
Voice UX Architecture | ||
Code2Flow | ||
Generative UI |
Docs: jangtrinh.github.io/design-os-3d-blender · Changelog: CHANGELOG.md · Index for AI agents: llms.txt
Contributing and license
CONTRIBUTING.md·CODE_OF_CONDUCT.md·SECURITY.md·PRIVACY.mdPolyForm Shield 1.0.0. FREE to use and modify, including for paid client work; you may not resell it or build a competing product from it.
Built by
Built by Jang Trịnh, creative technologist and autonomous system architect. More projects, case studies and writing at jang.work.
GitHub · LinkedIn · Hub · YouTube · X
Listed on
Also listed in the Official MCP Registry (io.github.jangtrinh/design-os-3d-blender), the awesome-mcp-servers list by TensorBlock and SkillsMP.
If design-os-3d-blender saves you time, a star on GitHub helps other engineers and AI agents find it.
Available Tools
4 toolsblender_runtime_statusA
Inspect the host environment for Blender 5.2 availability, OS, and knowledge readiness.
Returns: JSON string describing Blender binary availability, paths, and status.
Inputs: no named parameters. Returns: result
execute_blender_passA
Execute a bpy Python script in headless Blender and verify the AGENT_OK sentinel contract.
Args: script_path: Path to the Python script to execute inside Blender. blend_path: Optional path to an existing .blend file to open.
Returns: JSON string containing execution returncode, stdout snippet, and AGENT_OK / AGENT_FAIL sentinel.
Inputs: script_path (required), blend_path. Returns: result
query_blender_knowledgeA
Query the verified bpy 5.2 knowledge base for modeling, shading, modifiers, and gate rules.
Args: query: Search keywords (e.g., 'bevel modifier', 'pbr shader', 'watertight mesh', 'cycloid drive'). topic: Optional topic filter (e.g., '00-foundations', '10-modeling', '20-shading', '60-pipeline').
Returns: JSON string containing matching knowledge entries, guidelines, and code snippets.
Inputs: query (required), topic. Returns: result
validate_part_specA
Validate a 3D part specification (spec.json) against design:os requirements.
Args: spec_path: Path to the part specification JSON file.
Returns: JSON string containing validation status, errors, and checked dimensions.
Inputs: spec_path (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a clearly different part of the pipeline: environment inspection, script execution, knowledge lookup, and spec validation. There is no practical overlap, and descriptions make the boundaries explicit (e.g., execute vs. validate operate on scripts vs. specs).
Three tools follow a clean verb_noun pattern (execute_blender_pass, query_blender_knowledge, validate_part_spec) with a shared snake_case convention. blender_runtime_status is a noun-phrase status probe rather than an action verb, a minor but noticeable deviation from the otherwise predictable pattern.
Four tools is on the lean side but each maps to a distinct stage of the headless Blender workflow. Nothing feels redundant or padded, though the surface is minimal enough that a slightly richer set would be expected for the stated scope.
The core loop is covered: check the environment, consult the knowledge base, run bpy scripts, and validate output specs. Minor gaps exist — there is no tool to author or repair a spec, enumerate knowledge topics, or inspect/render resulting assets beyond the AGENT_OK sentinel — but agents can work around these via script execution.
Maintenance
Related MCP Connectors
Parametric 3D CAD for AI agents: build print-ready parts, check them, export STL, 3MF or STEP.
Text-to-CAD: build exact STEP or 3MF/STL on the server, each stated requirement measured.
A browser 3D CAD for your AI: it scripts real-size models, uCAD builds them and returns pictures.
CAD in ChatGPT and Claude: editable parts, STEP/STL/drawings, in-chat 3D, automatic checks.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to design, modify, and verify exact B-rep 3D CAD models by running build123d scripts on an OpenCascade kernel, with live three.js preview, collision and FDM printability checks, text-based spatial perception, user notes/sketch annotations, version history, and one-click export to OrcaSlicer.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to turn natural-language descriptions and dimensional sketches into validated, watertight 3D-printable STL files by compiling build123d scripts, inspecting meshes, and rendering deterministic multiview previews.MIT
- AlicenseBqualityBmaintenanceEnables AI agents to plan, generate, inspect, validate, repair, preview and hand off 3D models across five interchangeable geometry engines (procedural, OpenSCAD, Blender, CadQuery and hosted text-to-3D). Profile-based validation for print, CAD, game and web purposes keeps outputs correct, while CPU previews and single-file Three.js viewers make results visible and shareable.213MIT
- AlicenseCqualityBmaintenanceEnables AI assistants to drive a live Blender session through 74 structured, allowlisted tools covering scene management, mesh modeling, modifiers, materials, lighting, rigging, animation, physics, rendering, and multi-step orchestration — all without eval/exec and with localhost-only, token-authenticated, thread-safe bridging. Supports planning and visual validation of preview renders for end-to-end 3D workflows.74GPL 3.0