# Openscad Mcp

> MCP Server for OpenSCAD

- **Type:** MCP server
- **Install:** `agentstack add mcp-petrijr-openscad-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [petrijr](https://agentstack.voostack.com/s/petrijr)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [petrijr](https://github.com/petrijr)
- **Source:** https://github.com/petrijr/openscad-mcp

## Install

```sh
agentstack add mcp-petrijr-openscad-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OpenSCAD MCP Server

[](https://github.com/petrijr/openscad-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org) [](https://github.com/astral-sh/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):

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

Run the MCP server (stdio):

```bash
openscad-mcp
```

Example tool call arguments (conceptual JSON payload):

```json
{
    "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//preview.png`).

Run tests:

```bash
pytest -q
pytest -q -m "not integration"
```

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

```bash
./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:

```bash
mkdir -p artifacts
docker compose build
```

Run the MCP server via Docker (stdio passthrough):

```bash
./scripts/openscad-mcp-docker
```

Windows PowerShell:

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

```json
{
    "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:

```json
{
    "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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [petrijr](https://github.com/petrijr)
- **Source:** [petrijr/openscad-mcp](https://github.com/petrijr/openscad-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-petrijr-openscad-mcp
- Seller: https://agentstack.voostack.com/s/petrijr
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.