openscad-mcp-server 0.8.0

MCP server for OpenSCAD 3D model generation, compilation, and visual inspection

openscad-mcp-server

An MCP server that gives LLMs the ability to design, build, and visually verify 3D models using OpenSCAD — all through natural conversation.

The server handles the entire workflow: discovering and downloading OpenSCAD libraries on demand, saving code, compiling STL files in Docker/Finch containers, rendering 8-angle inspection images, and returning those images directly to the LLM's vision model as inline base64 PNGs. A built-in workflow prompt guides the LLM through systematic per-angle inspection with confidence scoring, so it catches defects before declaring a model complete.

Why this exists

LLMs can write OpenSCAD code, but they can't run it, see the result, or iterate on mistakes. This server closes that loop. The LLM writes code, the server compiles and renders it in a container, and the LLM sees the rendered model from 8 angles — then decides whether to fix issues or finalize.

Key design choices:

• Vision-native: Rendered images come back as MCP ImageContent blocks, not file paths. The LLM sees the model directly.
• Zero config: The init tool auto-detects Docker or Finch and persists settings via the LLM's memory mechanism. No env vars or config files needed.
• Library-aware: Libraries are discovered from the official OpenSCAD catalog and downloaded on demand. The server enforces that the LLM reads library source code before using it — no guessing at APIs.
• Correctness-first: The workflow prompt requires per-angle confidence scoring (overall = min of all angles) and forbids declaring a model complete below 0.5 confidence.

Quick start

Prerequisites

• Docker or Finch installed and running
• Python 3.11+ (for development) or uv (for running directly)

Run with uvx (no install needed)

uvx openscad-mcp-server

Or install and run

pip install openscad-mcp-server
openscad-mcp-server

The server communicates over stdio, so it's meant to be launched by an MCP client (Claude Desktop, Kiro, etc.), not run interactively.

Build the container images

The server needs two container images for compiling and rendering. Build them from the included Dockerfiles:

docker build -f Dockerfile.build -t openscad-build .
docker build -f Dockerfile.render -t openscad-render .

Or with Finch:

finch build -f Dockerfile.build -t openscad-build .
finch build -f Dockerfile.render -t openscad-render .

MCP client configuration

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "openscad": {
      "command": "uvx",
      "args": ["openscad-mcp-server"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "openscad": {
      "command": "uvx",
      "args": ["openscad-mcp-server"]
    }
  }
}

Tools

The server exposes 11 tools:

Tool	Description
init	Auto-detect Docker/Finch, configure working directory, return persistence content
save-code	Save OpenSCAD code to the working area (enforces library review)
build-stl	Compile .scad → .stl in a container
render-images	Render STL from 8 camera angles, return inline base64 PNG images
browse-library-catalog	Fetch the official OpenSCAD library listing
fetch-library	Download a library from its source repository
read-library-source	Read library .scad files and extract module signatures
list-reviewed-libraries	Show which libraries have been reviewed this session
submit-feedback	Record user feedback with artifact snapshots and confidence data
list-feedback	List all feedback records for analysis
finalize	Copy working area artifacts to the final output directory

Resources

Resource	URI	Description
Syntax Reference	openscad://syntax-reference	OpenSCAD language reference (primitives, transforms, booleans, modules)
Library Reference	openscad://library-reference/{name}	Dynamic reference generated from fetched library source
Common Pitfalls	openscad://pitfalls	Manifold errors, z-fighting, boolean order, missing $fn, etc.

Prompts

Prompt	Description
openscad-workflow	Full step-by-step workflow: init → library discovery → code → build → render → inspect → iterate → finalize

How the workflow works

User: "Make me a phone stand with a 75° angle"
  │
  ▼
┌─────────────────────────────────────────────┐
│ 1. init          → detect Docker/Finch      │
│ 2. browse-catalog → find relevant libraries │
│ 3. fetch-library  → download BOSL2          │
│ 4. read-source    → understand the API      │
│ 5. save-code      → write OpenSCAD code     │
│ 6. build-stl      → compile to STL          │
│ 7. render-images  → 8 angles, inline PNGs   │
│ 8. inspect        → per-angle confidence     │
│ 9. iterate        → fix issues, re-render   │
│ 10. finalize      → copy to output dir      │
└─────────────────────────────────────────────┘
  │
  ▼
Output: model.stl + model.scad + 8 inspection images

The LLM inspects each rendered angle individually, assigns per-angle confidence scores, and computes the overall confidence as the minimum across all angles. If any angle scores below 0.5, the LLM must iterate before finalizing.

Artifact layout

{working_dir}/
├── working/          # Latest iteration (overwritten each cycle)
│   ├── model.scad
│   ├── model.stl
│   └── renders/
│       ├── front.png
│       ├── back.png
│       ├── left.png
│       ├── right.png
│       ├── top.png
│       ├── bottom.png
│       ├── front-right-top-iso.png
│       └── back-left-top-iso.png
├── output/           # Final output (populated on finalize)
├── libraries/        # Downloaded OpenSCAD libraries
└── feedback/         # User feedback records with artifact snapshots

Development

# Clone and install with test dependencies
git clone https://github.com/your-org/openscad-mcp-server.git
cd openscad-mcp-server
uv sync --extra test

# Run tests
uv run pytest tests/ -v

# Run with Hypothesis verbose output
uv run pytest tests/ -v --hypothesis-show-statistics

Test suite

The test suite includes 51 tests covering all 25 correctness properties from the design spec, validated with Hypothesis property-based testing:

• Save-code round trip and filename normalization
• Container command generation (runtime-agnostic)
• Mount correctness and error propagation
• Render output (8 angles, PNG format, MCP ImageContent blocks)
• Library catalog parsing, caching, and fetch error handling
• Feedback record completeness, index round trip, confidence disagreement
• Working area overwrite invariant and finalize correctness
• Session state tracking and confidence score computation
• Version-tag matching for release pipeline
• Server registration (tools, resources, prompts)

CI/CD

• PR merge → main: Automatically creates a git tag and GitHub release from the version in pyproject.toml
• Tag push (v*): Builds and publishes to PyPI using trusted publishing (OIDC)

License

MIT