Skip to main content
Glama
design-os-3d-blender

design-os-3d-blender

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

From 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

docs/reviews/ck-001/r02

DC-01

A desk robot: printed parts, a carrier board, an assembly film

docs/reviews/dc-01/r03

Robot arm

A printable arm, with gated plates

builds/robot-arm-print-assembly

Nodestack

Modular industrial storage

docs/reviews/nodestack/r03

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

blender_runtime_status

Host, Python, and whether a Blender 5.2 binary is on the path. Call this first.

query_blender_knowledge

Search the verified bpy 5.2 knowledge base in knowledge/ before writing a script.

validate_part_spec

Check a spec.json: units in mm, target dimensions, tolerance, minimum wall.

execute_blender_pass

Run a headless pass and read the AGENT_OK or AGENT_FAIL line.

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

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

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

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

Verify:

python3 scripts/self_check.py

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

Prompt 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):

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.

Docs: jangtrinh.github.io/design-os-3d-blender · Changelog: CHANGELOG.md · Index for AI agents: llms.txt

Contributing and license

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 tools
blender_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

    A3.8/5.0

    Scored across 4 tools

    Disambiguation5/5

    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).

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      21
      3
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables 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.
      74
      GPL 3.0