OpenSCAD MCP Server

An open-source, lightweight Model Context Protocol (MCP) server that exposes a headless OpenSCAD 3D engine as a set of tools to AI agents. It allows LLMs (like Gemini or Claude) to programmatically write OpenSCAD scripts, compile them, render visual snapshots, and export functional 3D CAD files.

---

Features

• 🤖 AI-Driven Parametric Design: AI agents can draft mathematically precise parts in code.
• 👁️ Visual Feedback Loop: The server compiles and renders the .scad code into a PNG image locally using software OpenGL rendering. The agent inspects this image inline to self-correct design mistakes.
• 📦 Standard Library Support: Includes BOSL, BOSL2, and MCAD out of the box so the AI can generate advanced gears, screw threads, joints, and enclosures.
• 💾 Multiple Export Formats: The AI can compile and export designs directly to standard formats like .stl, .3mf, .dxf, and .svg saved on local storage.
• 🔌 Direct SSE Support: Built-in Server-Sent Events (SSE) server using FastAPI, making it directly discoverable by the mcp-router gateway.

---

System Architecture

graph TD
    User([User Chat Client])
    Client[LLM Client / Editor]
    Gateway[MCP Gateway / Host]
    Server[openscad-mcp Container]
    CLI[OpenSCAD CLI]
    Xvfb[X Virtual Framebuffer]
    Disk[(Output Disk Storage)]

    User -->|Prompts for CAD| Client
    Client -->|JSON-RPC via SSE/Stdio| Gateway
    Gateway -->|JSON-RPC| Server
    Server -->|Writes temp code| CLI
    Server -->|xvfb-run| Xvfb
    CLI -->|Renders PNG via Mesa OpenGL| Xvfb
    CLI -->|Compiles STL| Disk
    Xvfb -->|Return PNG bytes| Server
    Server -->|Returns ImageContent| Gateway
    Gateway -->|Sends PNG to Client| Client
    Client -->|Displays inline preview| User

Loading

---

Exposed Tools

1. openscad_render_code

Compiles OpenSCAD code and captures an isometric snapshot of the model using software OpenGL.

• Arguments:
  • code (string, required): Full valid OpenSCAD source code.
  • width (integer, default: 1024): Snapshot width in pixels.
  • height (integer, default: 1024): Snapshot height in pixels.
• Returns: PNG image data as an ImageContent object and compilation logs.

2. openscad_export_code

Compiles OpenSCAD code and exports it as a physical file on the server.

• Arguments:
  • code (string, required): Full valid OpenSCAD source code.
  • filename (string, required): Target filename (e.g. bracket.stl, spool_holder.3mf, faceplate.dxf).
• Returns: Export success message, final path on disk, and file size.

---

Docker Compose Configuration

Add the service block to your compose stacks:

  openscad-mcp:
    image: ghcr.io/<your-username>/openscad-mcp:latest
    container_name: openscad-mcp
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - ./output:/output
    # Add to your custom networks if routing through a gateway or proxy
    # networks:
    #   - mcp_network

---

License

This project is open-source and available under the MIT License.