Openscad

CI License Python Ruff

Overview

OpenSCAD MCP Server exposes the OpenSCAD CLI as Model Context Protocol (MCP) tools so MCP-compatible clients (including LLM-based clients) can validate, render, and export parametric 3D models using OpenSCAD.

This repo targets a v1.0 tool surface: stable, minimal, deterministic, and local-first (stdio transport only).

Tools

All tool details (args, options, response payloads) are documented in docs/TOOLING.md.

Core:

• ping: server + OpenSCAD discovery metadata
• list_formats: supported export/preview formats
• validate_scad: compile validation + parsed diagnostics
• export_model: export stl/3mf/off
• render_preview: export png
• render_scad: export model + preview in one call
• batch_render_scad: run multiple parameter variants sequentially

Templates & modules:

• list_templates / render_template: built-in parametric templates shipped with the server
• list_modules / render_module: render from a simple module registry (OPENSCAD_MCP_MODULE_ROOT)

Artifact ergonomics (opt-in, per call via options):

• inline_artifact_bytes: return base64 bytes in responses (size-limited)
• introspect_artifacts: basic artifact metadata inspection (size-limited)
• use_cache: content-addressed cache (requires OPENSCAD_MCP_CACHE_ROOT)

Quickstart (Local)

Prerequisites:

• Python 3.10+
• OpenSCAD installed and openscad available on your PATH (or set OPENSCAD_MCP_OPENSCAD_PATH)

Install (editable, recommended via venv):

python -m venv .venv
. .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"

Run the MCP server (stdio):

openscad-mcp

Example tool call arguments (conceptual JSON payload):

{
    "tool": "render_scad",
    "args": {
        "scad_source": "cube([w,h,d]);",
        "params": {
            "w": 10,
            "h": 20,
            "d": 5
        },
        "options": {
            "format": "stl",
            "imgsize": [
                512,
                512
            ],
            "inline_artifact_bytes": true
        }
    }
}

Artifacts are produced in a per-request build directory:

• If your MCP client can read local paths, set OPENSCAD_MCP_KEEP_ARTIFACTS=true (and optionally OPENSCAD_MCP_ARTIFACT_ROOT) so returned artifact.path values remain valid after the tool returns.
• If your MCP client cannot read local paths, use inline_artifact_bytes=true (subject to OPENSCAD_MCP_MAX_INLINE_BYTES).
  • For some clients, inline_artifact_bytes=true also results in an image attachment for render_preview / render_scad responses.

When OPENSCAD_MCP_ARTIFACT_ROOT is set, each request writes to a unique subdirectory (for example: ./artifacts/<uuid>/preview.png).

Run tests:

pytest -q
pytest -q -m "not integration"

Run integration tests inside the Docker image (real OpenSCAD):

./scripts/pytest-integration-docker

Docker (Recommended for Isolation)

This server uses MCP stdio transport (no network listener). To run it in Docker while still exposing a stdio MCP process to a host MCP client, use the provided wrapper which forwards stdin/stdout to a container.

Build the image and create a host-visible artifacts directory:

mkdir -p artifacts
docker compose build

Run the MCP server via Docker (stdio passthrough):

./scripts/openscad-mcp-docker

Windows PowerShell:

.\scripts\openscad-mcp-docker.ps1

Artifacts are written inside the container under /artifacts and are volume-mounted to ./artifacts on the host. If you need to enforce output size limits, set OPENSCAD_MCP_MAX_OUTPUT_BYTES.

Note: the container entrypoint uses an openscad-headless wrapper that prefers xvfb-run for PNG rendering, but falls back to QT_QPA_PLATFORM (default minimal) if xvfb-run/xauth are unavailable.

MCP Client Configuration Example (JetBrains AI)

Set the working directory to the project root folder.

{
    "mcpServers": {
        "openscad": {
            "command": "powershell.exe",
            "args": [
                "-NoProfile",
                "-ExecutionPolicy",
                "Bypass",
                "-File",
                ".\\scripts\\openscad-mcp-docker.ps1"
            ]
        }
    }
}

Screenshots

Model generation + validation:

Preview rendering + model export:

Module Registry Format

If OPENSCAD_MCP_MODULE_ROOT is set, it must contain an index.json manifest plus *.scad files:

{
    "modules": [
        {
            "id": "my_part",
            "description": "Example module.",
            "entry": "my_part"
        }
    ]
}

The server will load my_part.scad and call my_part() (or entry if it already includes parentheses).

Configuration

Environment variables:

• OPENSCAD_MCP_LOG_LEVEL: log level (default INFO)
• OPENSCAD_MCP_OPENSCAD_PATH: optional path to openscad (overrides PATH discovery)
• OPENSCAD_MCP_QT_QPA_PLATFORM: Qt platform plugin for headless fallback (default minimal)
• OPENSCAD_MCP_TIMEOUT_S: OpenSCAD subprocess timeout in seconds (default 30)
• OPENSCAD_MCP_ARTIFACT_ROOT: optional root directory for per-request build dirs
• OPENSCAD_MCP_KEEP_ARTIFACTS: if true, keep per-request build dirs
• OPENSCAD_MCP_MAX_OUTPUT_BYTES: fail if the generated artifact exceeds this size
• OPENSCAD_MCP_MAX_INLINE_BYTES: max bytes to inline when inline_artifact_bytes=true (default 5 MB)
• OPENSCAD_MCP_MAX_INTROSPECT_BYTES: max bytes to read for introspection (default 2 MB)
• OPENSCAD_MCP_CACHE_ROOT: root directory for artifact cache (enables use_cache=true)
• OPENSCAD_MCP_MODULE_ROOT: module registry root containing index.json + *.scad files
• OPENSCAD_MCP_INCLUDE_ROOTS: comma-separated allowlist for use/include (best-effort enforcement)

Security Notes

This server is designed to be local-first and run over stdio. Do not expose it directly to the internet.

OpenSCAD compilation should be treated as untrusted workload (CPU/memory heavy models, file use/include, etc). See docs/SECURITY.md for the project security stance and recommendations.

Documentation & Examples

• Tool surface and payloads: docs/TOOLING.md
• Security posture: docs/SECURITY.md
• Example prompts (copy/paste for MCP clients): examples/README.md
• Contributing: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Changelog: CHANGELOG.md

Roadmap

The v1.0 tool surface is implemented. Future enhancements are tracked via GitHub issues (e.g. more templates, deeper OpenSCAD diagnostics coverage, additional formats, optional session-like workflows).

License

MIT

Acknowledgement

Pretty much the whole project was generated With ChatGPT 5.1 using Codex CLI inside JetBrains PyCharm. The goal of this project is to investigate the implementation of MCP protocol in Python.