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 uses the current working directory so files are visible in your IDE. Settings are persisted 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.

The server uses the official openscad/openscad Docker Hub image for both STL compilation and rendering. It's pulled automatically on first use — no manual image builds needed.

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"]
    }
  }
}

The server auto-detects the workspace directory from its process working directory. If your MCP client doesn't set the cwd to the workspace folder, you can override it with the OPENSCAD_WORKSPACE environment variable in your MCP config:

{
  "mcpServers": {
    "openscad": {
      "command": "uvx",
      "args": ["openscad-mcp-server"],
      "env": {
        "OPENSCAD_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Tools

The server exposes 14 tools:

Resources

Prompts

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

your-project/
├── 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 72 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