DESIGN:OS 3D Blender Agent (design-os-3d-blender)

Parametric 3D mechanical parts generator, headless Blender Python (bpy) pipeline, and embedded Three.js CAD showcase engine.

Generate dimensionally accurate gears, enclosures, drone frames, and exploded mechanical assemblies from plain-English specs or JSON parameters, complete with glTF/STL exports and interactive browser inspection.

design-os-3d-blender is a free MCP server (Model Context Protocol, stdio) for Blender. Connect it to Claude Code, Codex, Cursor or any MCP client to model, render and verify parts in Blender 5.2 LTS. Free, nothing sold, source-available under PolyForm Shield 1.0.0.

Quickstart · What it makes · Install · How it works · Commands · Limits

Why this exists

Text-to-3D diffusion models produce melted, non-manifold blobs that cannot be 3D-printed, machined, or cleanly animated in web viewers. design-os-3d-blender drives Blender's Python API (bpy) and Three.js deterministically to produce crisp mechanical geometry and interactive CAD showcases.

Quickstart

1. Install the plugin or CLI

In Claude Code:

/plugin marketplace add jangtrinh/design-os-3d-blender
/plugin install design-os-3d-blender@design-os-3d-blender

Or from your terminal (Codex, Gemini CLI, Antigravity, OpenCode, or standalone CLI):

git clone https://github.com/jangtrinh/design-os-3d-blender.git
cd design-os-3d-blender
python3 scripts/self_check.py

2. Ask in plain English

Open your project in your AI coding agent and describe what you need:

"Generate a parametric 24-tooth helical gear and mounting bracket in headless Blender and export glTF + STL artifacts."

"Build an interactive Three.js CAD viewer page with exploded-view scrubbing, wireframe toggle, and orthographic camera presets."

"Audit the exported mesh topology for non-manifold edges, zero-area faces, and bounding-box dimensional tolerances."

3. Verify your setup

python3 scripts/self_check.py

What it makes

Every deliverable produced by design-os-3d-blender is backed by a deterministic verification gate rather than freehand AI guesswork.

_{Prompt: "Generate a parametric 24-tooth helical gear and mounting bracket in headless Blender and export glTF + STL artifacts."}

Installation

Choose the setup that matches your AI coding agent. Every option installs the same canonical skill (skills/design-os-3d-blender/SKILL.md) and /doctor diagnostic suite.

Claude Code

Run these two commands inside Claude Code:

/plugin marketplace add jangtrinh/design-os-3d-blender
/plugin install design-os-3d-blender@design-os-3d-blender

OpenAI Codex

Install to your personal Codex skills directory:

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-blender

Gemini CLI & 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-blender

OpenCode, Cursor, Windsurf & 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-blender

python3 scripts/self_check.py

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-blender

Usage & Prompt Cookbook

Once installed, skills/design-os-3d-blender/SKILL.md activates automatically when your prompt matches its domain triggers. Browse docs/cookbook.md for copy-paste prompt recipes.

Generate & Scaffold

"Generate a parametric 24-tooth helical gear and mounting bracket in headless Blender and export glTF + STL artifacts."

Audit & Verify

"Build an interactive Three.js CAD viewer page with exploded-view scrubbing, wireframe toggle, and orthographic camera presets."

Export & Automate

"Audit the exported mesh topology for non-manifold edges, zero-area faces, and bounding-box dimensional tolerances."

Commands & Diagnostics

How it works

1. Intent Routing — Your AI agent matches your request against skills/design-os-3d-blender/SKILL.md frontmatter triggers.
2. Progressive Context Loading — Only the entry-point SKILL.md router loads initially; detailed recipes and scripts load on demand.
3. Deterministic Execution — Domain scripts and contracts execute locally with reproducible inputs and outputs.
4. Gate Verification — scripts/self_check.py and domain verifiers (python3 scripts/self_check.py) validate the artifact before completion.
5. Zero-Telemetry Delivery — Verified files are written directly to your workspace with zero external network calls.

User Prompt / CLI Invocation
            │
            ▼
┌───────────────────────────────────────────────┐
│ skills/design-os-3d-blender/SKILL.md
│ Progressive disclosure router & hard rules    │
└───────────┬───────────────────────────────────┘
            │ loads on demand
            ▼
┌───────────────────────────────────────────────┐
│ python3 scripts/self_check.py
│ Deterministic build & contract enforcement    │
└───────────┬───────────────────────────────────┘
            │ verifies
            ▼
┌───────────────────────────────────────────────┐
│ python3 scripts/self_check.py + /doctor       │
│ Zero-telemetry local verification gate        │
└───────────────────────────────────────────────┘

What loads when

design-os-3d-blender uses progressive context disclosure so your agent's context window stays fast and focused:

File structure

design-os-3d-blender/
├── .claude-plugin/
│   ├── plugin.json                 # Claude Code plugin manifest
│   └── marketplace.json            # Claude Code marketplace catalog
├── .codex-plugin/
│   └── plugin.json                 # OpenAI Codex plugin & interface manifest
├── .agents/
│   └── plugins/marketplace.json    # Cross-agent local plugin registry
├── .factory-plugin/
│   ├── plugin.json                 # Factory / Droid plugin manifest
│   └── marketplace.json            # Factory marketplace metadata
├── skills/
│   └── design-os-3d-blender/
│       └── SKILL.md                # Canonical agent skill entrypoint
├── commands/
│   └── doctor.md                   # /doctor diagnostic slash command
├── prompts/
│   └── doctor.md                   # Codex diagnostic prompt mirror
├── scripts/
│   └── self_check.py               # Deterministic repository & skill self-check
├── docs/
│   ├── cookbook.md                 # Copy-paste prompt recipes by job
│   └── llms.txt                    # GEO / LLM discovery index
├── PRIVACY.md                      # Zero-telemetry & local-first privacy commitment
├── SECURITY.md                     # Vulnerability disclosure & security policy
├── CONTRIBUTING.md                 # Contribution workflow & verification rules
├── CODE_OF_CONDUCT.md              # Contributor Covenant code of conduct
├── CHANGELOG.md                    # Release history
├── llms.txt                        # Root LLM indexing manifest
├── LICENSE                         # PolyForm Shield 1.0.0
└── README.md

Quality bar & Limitations

It's working if...

• python3 scripts/self_check.py prints ok: design-os-3d-blender self-check passed (design-os-3d-blender) and exits 0.
• python3 scripts/self_check.py passes with zero contract or test regressions.
• Your AI coding agent loads skills/design-os-3d-blender/SKILL.md automatically when given any prompt from docs/cookbook.md.
• Network traffic during execution remains zero (guaranteed by PRIVACY.md).

When not to use

• Sheet-metal or paperboard folding dielines where 2D crease patterns govern topology (use design-os-origami).
• Organic character sculpting or AAA rigged game characters requiring manual ZBrush artistry.
• 2D vector UI motion walkthroughs (use design-os-svg-animation).

DESIGN:OS Ecosystem

design-os-3d-blender is one of the 13 source-available engines in the DESIGN:OS ecosystem:

Contributing, Governance & License

• Contributing: See CONTRIBUTING.md for pull request guidelines and verification gates (python3 scripts/self_check.py).
• Code of Conduct: Governed by CODE_OF_CONDUCT.md.
• Security & Privacy: Zero telemetry — see SECURITY.md and PRIVACY.md.
• Changelog & LLM Index: Track releases in CHANGELOG.md and machine-readable index in llms.txt.
• License: PolyForm Shield 1.0.0 © Jang Trinh. Free to use and modify, including for paid client work; you may not resell it or build a competing product from it.

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 with design-os-3d-blender: 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): 27-second fan-made 3D model of the Nowa desktop product, built with design-os-3d-blender.

More: design:os by Jang on YouTube.

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.