OpenSCAD MCP Server

OpenSCAD MCP Server

A Model Context Protocol (MCP) server that gives AI assistants the ability to render, export, and analyze 3D models using OpenSCAD. Built with FastMCP for Python.

Prerequisites

• OpenSCAD installed on your system
• uv (recommended) or Python 3.10+

Installation

Claude Code

--refresh-package openscad-mcp makes uv re-resolve the package from GitHubon every start, so a new release is picked up automatically the next time theserver launches. Drop the flag to pin to whatever uv has cached, or add@v0.6.0 after the URL to pin a release.

Add the server with a single command:

claude mcp add openscad --transport stdio -- \
  uv run --refresh-package openscad-mcp --with git+https://github.com/quellant/openscad-mcp.git openscad-mcp

Or, if OpenSCAD is not on your PATH:

claude mcp add openscad --transport stdio \
  --env OPENSCAD_PATH=/path/to/openscad -- \
  uv run --refresh-package openscad-mcp --with git+https://github.com/quellant/openscad-mcp.git openscad-mcp

Use the --scope flag to control where the configuration is saved:

Claude Desktop

Add to your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "openscad": {
      "command": "uv",
      "args": [
        "run",
        "--refresh-package", "openscad-mcp",
        "--with", "git+https://github.com/quellant/openscad-mcp.git",
        "openscad-mcp"
      ],
      "env": {
        "OPENSCAD_PATH": "/usr/bin/openscad"
      }
    }
  }
}

Then restart Claude Desktop.

Cursor / Windsurf / VS Code

Add a .mcp.json file to your project root:

{
  "mcpServers": {
    "openscad": {
      "command": "uv",
      "args": [
        "run",
        "--refresh-package", "openscad-mcp",
        "--with", "git+https://github.com/quellant/openscad-mcp.git",
        "openscad-mcp"
      ]
    }
  }
}

Manual / Standalone

# Run directly from GitHub (no install required)
uv run --refresh-package openscad-mcp --with git+https://github.com/quellant/openscad-mcp.git openscad-mcp

# Or clone and run locally
git clone https://github.com/quellant/openscad-mcp.git
cd openscad-mcp
uv run openscad-mcp

Available Tools

Every tool response carries errors, warnings and hints parsed fromOpenSCAD's output. Check them: OpenSCAD exits 0 on a failed assert() or anunknown module and draws a blank scene.

Rendering

Assemblies

Parts are given inline as parts=[{name, code, place?, frame?, ghost?, mass_g?, motion?}] or in a check file (frames, quality, parts, checks, model). openscad-mcp check <file.yaml> runs a check file from the shell with a meaningful exit code, so make check is one call.

Export & Model Management

Measurement & Validation

Project Support

Usage Examples

Once connected, ask your AI assistant:

• "Render a cube with rounded edges"
• "Show me the front and top of this model with a scale bar"
• "What is the volume and are there any cavities?"
• "Cut a section through the lid at z = 12 and tell me the wall thickness"
• "Colour the body and lid differently and ghost the body"
• "What clearance should I use for an M3 screw and a press-fit 608 bearing?"
• "Compare the model before and after changing the radius to 15"
• "Export my gear model to STL"

The server also publishes MCP resources (openscad://conventions,openscad://cheatsheet, openscad://reference/{topic}) and serverinstructions with the coordinate and assembly conventions it expects. AClaude Code skill lives in skills/openscad-design/SKILL.md and the repo canbe installed as a Claude Code plugin (.claude-plugin/).

Tool Parameters

render

Each image costs roughly 640 vision tokens at 800x600; ask for the views thatanswer a question rather than all of them. Auto-fit renders (grounded=false)have no recoverable absolute scale, which the digest states.

*Exactly one of scad_content or scad_file must be provided.

All parameter parsers accept multiple input formats (JSON strings, lists, dicts, CSV) for AI assistant compatibility.

Configuration

Environment Variables

YAML Configuration

Create a config.yaml for advanced configuration:

server:
  name: "OpenSCAD MCP Server"
  version: "0.1.0"
  transport: stdio

rendering:
  max_concurrent: 5
  timeout_seconds: 300
  default_color_scheme: Cornfield

cache:
  enabled: true
  max_size_mb: 500
  ttl_hours: 24

security:
  rate_limit: 60
  max_file_size_mb: 10
  allowed_paths:          # null = no path validation at all (a warning is logged)
    - /home/me/projects/parts
  max_memory_mb: 4096

Security

Threat model

The server runs OpenSCAD on source it is handed. OpenSCAD can read any filethe process can read, through include <>, use <>, import() andsurface(), and can return what it read as echo output or as geometry. Theguarantees below hold only when allowed_paths is configured. Out of thebox it is unset, no path validation is performed, and the server logs awarning at startup saying so.

What is enforced:

• Path validation on arguments: scad_file, include_paths (in everytool) and export output_path must lie inside allowed_paths. Containmentuses resolved paths, so symlinks and .. cannot escape.
• Path validation on the dependency closure: every file OpenSCAD actuallyread is recorded with -d and checked after the run. If any lies outsideallowed_paths, the standard library directories, or the server temp dir,the output (image, mesh, echo text) is withheld and the call fails. Thiscloses the include <...>-as-data and surface(file=...) channels.
• Memory ceiling: each OpenSCAD process runs under RLIMIT_AS(max_memory_mb, default 4 GB) on POSIX hosts. OpenSCAD has no ceiling ofits own; a small minkowski() can otherwise consume all host memory.
• Timeout: timeout_seconds, default 300 s; partial stderr is kept.
• Echo channel bounds: echo_output is capped (200 lines, 2000 charsper line) and labelled as untrusted content from the rendered file.
• File size limits, variable name validation(^\$?[a-zA-Z_][a-zA-Z0-9_]*$) and model name validation (no pathtraversal) as before.

What is not enforced: no OS-level sandbox (no network isolation, nofilesystem namespace). For untrusted input run the server inside acontainer or under Landlock/bubblewrap with only the project directorymounted.

Why --hardwarnings is off

--hardwarnings stops OpenSCAD at the first warning but still exits 0, soit produced blank renders and silently truncated echo_output with noindication. Warnings now reach the assistant through the structuredwarnings, errors and hints fields on every tool response instead.Set MCP_HARD_WARNINGS=true to restore the flag.

Development

# Clone the repo
git clone https://github.com/quellant/openscad-mcp.git
cd openscad-mcp

# Install dependencies
uv sync --dev

# Run the server
uv run openscad-mcp

# Run tests
uv run pytest

# Lint & format
uv run ruff check src/ tests/
uv run black --check src/ tests/

# Type check
uv run mypy src/

Project Structure

openscad-mcp/
├── src/openscad_mcp/
│   ├── __init__.py          # Package exports
│   ├── server.py            # FastMCP server, all MCP tools and helpers
│   ├── types.py             # Pydantic models and enums
│   └── utils/
│       └── config.py        # Configuration with env/YAML/dotenv support
├── tests/                   # 300 tests, 80%+ coverage
├── pyproject.toml
└── README.md

Testing

# Run all tests with coverage
uv run pytest

# Run specific markers
uv run pytest -m unit
uv run pytest -m performance

# Run a single file
uv run pytest tests/test_helpers.py -v

Tests mock the OpenSCAD subprocess — no OpenSCAD installation required to run them. Coverage target: 80% minimum.

Troubleshooting

OpenSCAD Not Found

# Check if OpenSCAD is installed
which openscad        # Linux/macOS
where openscad.exe    # Windows

# Set the path explicitly
export OPENSCAD_PATH=/path/to/openscad

Server Not Connecting

# Verify the server starts correctly
uv run --refresh-package openscad-mcp --with git+https://github.com/quellant/openscad-mcp.git openscad-mcp

# In Claude Code, check MCP status
/mcp

Render Timeout

Increase the timeout:

export MCP_RENDER_TIMEOUT=600

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes with tests
4. Ensure tests pass (uv run pytest)
5. Open a Pull Request

Commit style: feat:, fix:, docs:, refactor:, chore:

License

MIT — see LICENSE

Acknowledgments

• FastMCP — Python MCP framework
• OpenSCAD — Programmable CAD software
• Model Context Protocol — The MCP specification