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

Add the server with a single command:

claude mcp add openscad --transport stdio -- \
  uv run --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 --with git+https://github.com/quellant/openscad-mcp.git openscad-mcp

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

Scope	Flag	Effect
Local (default)	--scope local	Available only to you in the current project
Project	--scope project	Shared with the team via .mcp.json
User	--scope user	Available to you across all projects

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",
        "--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",
        "--with", "git+https://github.com/quellant/openscad-mcp.git",
        "openscad-mcp"
      ]
    }
  }
}

Manual / Standalone

# Run directly from GitHub (no install required)
uv run --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

Rendering

Tool	Description
render_single	Render a single view with camera control, quality presets, and view presets
render_perspectives	Render multiple standard views (front, back, left, right, top, bottom, isometric) in parallel
compare_renders	Side-by-side before/after renders for visual comparison

Export & Model Management

Tool	Description
export_model	Export to STL, 3MF, AMF, OFF, DXF, or SVG
create_model	Create a new .scad file in the workspace
get_model	Read a model file and its metadata
update_model	Update an existing model's content
list_models	List all models in the workspace
delete_model	Delete a model file

Analysis & Validation

Tool	Description
validate_scad	Syntax-check code without a full render (errors, warnings, echo output)
analyze_model	Compute bounding box, dimensions, and triangle count via STL export
get_libraries	Discover installed OpenSCAD libraries
check_openscad	Verify OpenSCAD installation and version

Project Support

Tool	Description
get_project_files	List .scad files and their include/use dependency graph
clear_cache	Clear the render cache

Usage Examples

Once connected, ask your AI assistant:

• "Render a cube with rounded edges"
• "Show me this model from all angles"
• "Export my gear model to STL"
• "Compare the model before and after changing the radius to 15"
• "Validate this OpenSCAD code for errors"
• "What are the dimensions of this model?"

Tool Parameters

render_single

Parameter	Type	Default	Description
scad_content	string	—	OpenSCAD code to render*
scad_file	string	—	Path to .scad file*
view	string	—	Preset view: front, back, left, right, top, bottom, isometric, dimetric
camera_position	list/string	[70,70,70]	Camera eye position [x,y,z]
camera_target	list/string	[0,0,0]	Camera look-at point
image_size	list/string	[800,600]	Output dimensions [w,h] or "800x600"
color_scheme	string	Cornfield	OpenSCAD color scheme
variables	dict	{}	OpenSCAD -D variables
quality	string	—	draft, normal, or high
include_paths	list	—	Extra -I include directories
output_format	string	auto	auto, base64, file_path, or compressed

*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

Variable	Description	Default
OPENSCAD_PATH	Path to OpenSCAD executable	Auto-detected
MCP_TEMP_DIR	Temporary file directory	/tmp/openscad-mcp
MCP_TRANSPORT	Transport type: stdio, http, sse	stdio
MCP_HOST	Host for HTTP/SSE transport	localhost
MCP_PORT	Port for HTTP/SSE transport	8000
MCP_MAX_CONCURRENT_RENDERS	Max parallel renders	5
MCP_RENDER_TIMEOUT	Render timeout in seconds	300
MCP_CACHE_ENABLED	Enable render caching	true
MCP_CACHE_SIZE_MB	Max cache size in MB	500
MCP_CACHE_TTL_HOURS	Cache TTL in hours	24
MCP_LOG_LEVEL	Logging level	INFO
MCP_MAX_FILE_SIZE_MB	Max SCAD file size	10

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  # null = no restrictions

Security

• Path validation: scad_file and include_paths validated against configurable allowed_paths
• File size limits: Content checked against max_file_size_mb
• Variable name validation: Only ^[a-zA-Z_][a-zA-Z0-9_]*$ allowed (prevents injection)
• Subprocess timeout: Configurable, default 300s
• Model name validation: Alphanumeric, hyphens, and underscores only; no path traversal

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