Skip to main content
Glama
cad-blender-bridge

cad-blender-bridge

by DECRUX9812

cad-blender-bridge

An agentic bridge between natural-language CAD parameters, build123d (the OpenCascade B-Rep kernel) and headless Blender (bpy) — with an MCP server so any MCP-capable agent can drive the whole loop.

Ask an agent for "a planetary gearbox, module 1.5, 16-tooth sun, three 8-tooth planets, 10 mm thick" and get back a true multi-part B-Rep assembly, verified .step / .stl exports, a manifold-checked mesh, and a studio render — not a picture of gears.

verification render

Architecture

natural-language parameters (via MCP tool call)
        │
        ▼
┌─────────────────────────────────────────────────────────┐
│ build123d / OpenCascade B-Rep kernel                    │
│  • involute tooth profiles (20° pressure angle)         │
│  • sun + planets (PolarLocations, mesh-phased) + ring   │
│  • Mode.SUBTRACT bores, Z-axis edge fillets             │
│  • assertions: is_valid, volume > 0, exact bbox,        │
│    pairwise interference ≤ 0.1 ppm of volume            │
└─────────────────────────────────────────────────────────┘
        │  out/planetary_assembly.step  (B-Rep, CAD interchange)
        │  out/planetary_assembly.stl   (tessellated mesh)
        │  out/manifest.json            (build + verification manifest)
        ▼
┌─────────────────────────────────────────────────────────┐
│ headless Blender (blender --background --python …)      │
│  • STL import (wm.stl_import, legacy fallback)          │
│  • bmesh integrity: non-manifold edges, zero-area faces │
│  • Cycles studio render (EEVEE fallback): metallic      │
│    Principled BSDF, key + fill AREA lights,             │
│    orthographic isometric camera → 1024×1024 PNG        │
│  • out/verification_report.json                         │
└─────────────────────────────────────────────────────────┘
        ▲
        │  FastMCP("cad-blender-bridge") — stdio MCP server
        │  tools: build_parametric_gearbox,
        │         verify_and_render_blender,
        │         inspect_step_manifest

The gearbox is mechanically real: the ring tooth count is derived as sun_teeth + 2·planet_teeth, the planetary assembly condition (sun_teeth + ring_teeth) % planet_count == 0 is enforced, planets are rotationally phased so sun/planet/ring teeth mesh tooth-into-space, and a pairwise boolean intersection check proves no parts overlap.

Related MCP server: gitcad

Installation

Requires Python ≥ 3.11. Blender ≥ 4.x is optional (only needed for the verification/render stage).

git clone https://github.com/DECRUX9812/cad-blender-bridge.git
cd cad-blender-bridge
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

CLI usage

python -m cad_blender_bridge.generator \
    --module 1.5 --sun-teeth 16 --planet-teeth 8 --planet-count 3 \
    --thickness 10 --clearance 0.2 --out-dir out

Writes out/planetary_assembly.step, out/planetary_assembly.stl and out/manifest.json, and prints the manifest:

{
  "status": "ok",
  "step_path": "out/planetary_assembly.step",
  "stl_path": "out/planetary_assembly.stl",
  "volume_mm3": 12345.678,
  "is_valid_brep": true,
  "bbox_mm": {"x": 80.0, "y": 80.0, "z": 10.0},
  "params": {"module": 1.5, "sun_teeth": 16, "...": "..."}
}

Invalid parameter combinations (e.g. planets that cannot all mesh) raise ValueError before any geometry is built.

Headless Blender verification + render

blender --background --python src/cad_blender_bridge/verify_render.py -- \
    --input out/planetary_assembly.stl \
    --out out/verify.png \
    --report out/verification_report.json

The report contains non_manifold_edges, zero_area_faces, manifold_pass, dimensions_mm, mesh counts and the renderer used. The render is a 1024×1024 orthographic isometric studio shot (Cycles CPU, EEVEE fallback).

MCP server

python -m cad_blender_bridge.mcp_server   # stdio transport

Tools exposed:

Tool

What it does

build_parametric_gearbox(module, sun_teeth, planet_teeth, planet_count, thickness, clearance_mm)

Builds + verifies the B-Rep assembly, exports STEP/STL, returns the JSON manifest

verify_and_render_blender(stl_path, render_out, blender_bin)

Runs headless Blender mesh inspection + studio render, returns the JSON report (clear error if Blender is not in PATH)

inspect_step_manifest(manifest_path)

Returns the latest build manifest plus a tolerance-check summary

MCP client configuration

{
  "mcpServers": {
    "cad-blender-bridge": {
      "command": "/path/to/cad-blender-bridge/.venv/bin/python",
      "args": ["-m", "cad_blender_bridge.mcp_server"],
      "cwd": "/path/to/cad-blender-bridge"
    }
  }
}

Then ask your agent: "Build a module-2 planetary gearbox with a 20-tooth sun and four 10-tooth planets, verify it in Blender, and show me the render."

Tests

pytest

The suite generates real geometry into tmp_path, asserts non-empty STEP/STL exports, is_valid_brep is True, zero interference, and that increasing the module increases the assembly volume.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Connects MCP-capable agents to Blender and OpenSCAD for AI-driven 3D modeling, with tools and rules optimized for FDM-printable geometry.
      29
      34 PyPI
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables agents to create and manipulate 3D CAD models using natural language via MCP, with git-based versioning and manufacturing output generation.
      2
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents and MCP clients to perform 3D asset creation and verification: exact b-rep CAD, GLB validation with embedded certificates, mesh inspection, and physics scenes, with most tools running without Blender.
      36
      48 npm
      MIT