OpenSCAD MCP Server

OpenSCAD Model Context Protocol (MCP) - An intelligent assistant for 3D modeling with OpenSCAD and 3D printing workflow. Includes also a gradio app to test different LLMs with the Server.

Table of Contents

• Prerequisites
• Installation
• OpenSCAD Libraries
• Running the Application

Prerequisites

Before installing this application, you'll need to install the following software dependencies and set up your environment.

1. Install Python (Required)

This application requires Python 3.8 or higher.

Check if Python is installed:

python3 --version
# or
python --version

Install Python if needed:

2. Install OpenSCAD (Required)

OpenSCAD is the core 3D modeling software required for this application.

Windows:

1. Download the installer:

   • Go to OpenSCAD Downloads
   • Download "OpenSCAD x86 (64-bit) - exe installer" (or 32-bit if needed)
   • File size: ~20MB

2. Install:

   • Run the downloaded .exe file
   • Follow the installation wizard
   • Default installation path: C:\Program Files\OpenSCAD\

3. Find the executable path:

   • Typical location: C:\Program Files\OpenSCAD\openscad.exe
   • Or: C:\Program Files (x86)\OpenSCAD\openscad.exe

macOS:

1. Option A - Homebrew (Recommended):

   brew install openscad
   

   • Executable location: /opt/homebrew/bin/openscad (Apple Silicon) or /usr/local/bin/openscad (Intel)

2. Option B - Manual Download:

   • Download the .dmg file from OpenSCAD Downloads
   • Open the .dmg file and drag OpenSCAD to Applications folder
   • Executable location: /Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD

Linux:

Ubuntu/Debian:

# Official repositories (recommended for most users)
sudo apt update
sudo apt install openscad

# Executable location: /usr/bin/openscad

Linux Instructions: OpenSCAD Linux

Installation

1. Clone the Repository

git clone https://github.com/FeMa42/openscad_mcp.git
cd openscad_mcp

2. Create Virtual Environment (Recommended)

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

3. Install Python Dependencies

pip install -r requirements.txt

If you encounter dependency conflicts:

# Try upgrading pip first
pip install --upgrade pip

# Or install with --no-deps flag for specific packages
pip install --no-deps package_name

4. Configure Application Paths

You need to update the configuration file with the correct paths to your installed software.

Edit gradio_app/config.json:

The configuration file should look like this, but with paths updated for your system:

{
    "mcpServers": {
        "openscad": {
            "command": "/path/to/your/python",
            "args": [
                "/path/to/your/openscad_mcp/openscad_fastmcp_server.py"
            ],
            "transport": "stdio",
            "env": {
                "PYTHONUNBUFFERED": "1",
                "OPENSCAD_OUTPUT_DIR": "/path/to/your/openscad_mcp/output",
                "OPENSCAD_INFO_DIR": "/path/to/your/openscad_mcp/openscad_info",
                "FAISS_INDEX_PATH": "/path/to/your/openscad_mcp/faiss_index_modern",
                "OPENSCAD_USER_LIBRARY_PATH": "/path/to/openscad/libraries",
                "OPENSCAD_EXECUTABLE": "/path/to/openscad/executable",
                "EMBEDDING_PROVIDER": "local",
                "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
                "PRUSASLICER_PATH": "/path/to/prusaslicer/executable"
            }
        }
    }
}

Update the following paths in the config file:

For Windows:

{
    "mcpServers": {
        "openscad": {
            "command": "C:\\path\\to\\your\\venv\\Scripts\\python.exe",
            "args": [
                "C:\\path\\to\\your\\openscad_mcp\\openscad_fastmcp_server.py"
            ],
            "transport": "stdio",
            "env": {
                "PYTHONUNBUFFERED": "1",
                "OPENSCAD_OUTPUT_DIR": "C:\\path\\to\\your\\openscad_mcp\\output",
                "OPENSCAD_INFO_DIR": "C:\\path\\to\\your\\openscad_mcp\\openscad_info",
                "FAISS_INDEX_PATH": "C:\\path\\to\\your\\openscad_mcp\\faiss_index_modern",
                "OPENSCAD_USER_LIBRARY_PATH": "C:\\Users\\YourName\\Documents\\OpenSCAD\\libraries",
                "OPENSCAD_EXECUTABLE": "C:\\Program Files\\OpenSCAD\\openscad.exe",
                "EMBEDDING_PROVIDER": "local",
                "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
                "PRUSASLICER_PATH": "C:\\Program Files\\PrusaSlicer\\prusa-slicer.exe"
            }
        }
    }
}

For macOS:

{
    "mcpServers": {
        "openscad": {
            "command": "/Users/yourusername/openscad_mcp/venv/bin/python",
            "args": [
                "/Users/yourusername/openscad_mcp/openscad_fastmcp_server.py"
            ],
            "transport": "stdio",
            "env": {
                "PYTHONUNBUFFERED": "1",
                "OPENSCAD_OUTPUT_DIR": "/Users/yourusername/openscad_mcp/output",
                "OPENSCAD_INFO_DIR": "/Users/yourusername/openscad_mcp/openscad_info",
                "FAISS_INDEX_PATH": "/Users/yourusername/openscad_mcp/faiss_index_modern",
                "OPENSCAD_USER_LIBRARY_PATH": "/Users/yourusername/Documents/OpenSCAD/libraries",
                "OPENSCAD_EXECUTABLE": "/Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD",
                "EMBEDDING_PROVIDER": "local",
                "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
                "PRUSASLICER_PATH": "/Applications/PrusaSlicer.app/Contents/MacOS/PrusaSlicer"
            }
        }
    }
}

For Linux:

{
    "mcpServers": {
        "openscad": {
            "command": "/home/yourusername/openscad_mcp/venv/bin/python",
            "args": [
                "/home/yourusername/openscad_mcp/openscad_fastmcp_server.py"
            ],
            "transport": "stdio",
            "env": {
                "PYTHONUNBUFFERED": "1",
                "OPENSCAD_OUTPUT_DIR": "/home/yourusername/openscad_mcp/output",
                "OPENSCAD_INFO_DIR": "/home/yourusername/openscad_mcp/openscad_info",
                "FAISS_INDEX_PATH": "/home/yourusername/openscad_mcp/faiss_index_modern",
                "OPENSCAD_USER_LIBRARY_PATH": "/home/yourusername/.local/share/OpenSCAD/libraries",
                "OPENSCAD_EXECUTABLE": "/usr/bin/openscad",
                "EMBEDDING_PROVIDER": "local",
                "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
                "PRUSASLICER_PATH": "flatpak run com.prusa3d.PrusaSlicer"
            }
        }
    }
}

Finding your exact paths:

• Current directory: Run pwd (macOS/Linux) or cd (Windows)
• Python path: Run which python (macOS/Linux) or where python (Windows)
• OpenSCAD path: Run which openscad (macOS/Linux) or where openscad (Windows)

OpenSCAD Libraries (Recommended)

The MCP server can leverage external OpenSCAD libraries for gears, fasteners, and more. Libraries are installed by cloning them into OpenSCAD's user library directory, and the server auto-detects them on startup.

Library directory by OS:

OS	Path
macOS	~/Documents/OpenSCAD/libraries/
Windows	%USERPROFILE%\Documents\OpenSCAD\libraries\
Linux	~/.local/share/OpenSCAD/libraries/

Create the directory if it doesn't exist, then install any of the following:

BOSL2 (Recommended)

The Belfry OpenSCAD Library v2 — the most comprehensive library, and the preferred library for gear generation.

cd ~/Documents/OpenSCAD/libraries/   # adjust for your OS
git clone https://github.com/BelfrySCAD/BOSL2.git

Usage in OpenSCAD: include <BOSL2/std.scad> and include <BOSL2/gears.scad>

MCAD

Community-maintained library for motors, bearings, fasteners, and basic shapes.

cd ~/Documents/OpenSCAD/libraries/   # adjust for your OS
git clone https://github.com/openscad/MCAD.git

parameterizable_gears

Parametric involute gear library (based on sadr0b0t/pd-gears).

cd ~/Documents/OpenSCAD/libraries/   # adjust for your OS
git clone https://github.com/sadr0b0t/pd-gears.git parameterizable_gears

Verifying Installation

The MCP server logs detected libraries on startup. You can also check that the OPENSCAD_USER_LIBRARY_PATH in gradio_app/config.json points to your library directory (see Configure Application Paths above).

Running the Application

1. Setting up API Keys

The application supports multiple AI models. You need at least one API key:

Option A: Environment Variables (Recommended)

# For OpenAI models (gpt-5, gpt-5-mini, gpt-oss)
export OPENAI_API_KEY="your-openai-api-key-here"

# For Anthropic Claude models (claude-4-sonnet, claude-4-opus, etc.)
export ANTHROPIC_API_KEY="your-anthropic-api-key-here"

# For Google Gemini models (gemini-2.5-pro, gemini-3.1-pro, etc.)
export GOOGLE_API_KEY="your-google-api-key-here"

# For OpenRouter models (Qwen3, Llama, DeepSeek, etc.)
export OPENROUTER_API_KEY="your-openrouter-api-key-here"

Make it permanent:

Windows:

• Add to System Environment Variables via System Properties > Advanced > Environment Variables

macOS/Linux:

# Add to your shell profile (~/.bashrc, ~/.zshrc, ~/.bash_profile)
echo 'export OPENAI_API_KEY="your-key-here"' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.bashrc
echo 'export GOOGLE_API_KEY="your-key-here"' >> ~/.bashrc
echo 'export OPENROUTER_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc

Option B: .env File

Create a .env file in the project root:

OPENAI_API_KEY=your-openai-api-key-here
ANTHROPIC_API_KEY=your-anthropic-api-key-here
GOOGLE_API_KEY=your-google-api-key-here
OPENROUTER_API_KEY=your-openrouter-api-key-here

Getting API Keys:

• OpenAI: platform.openai.com
• Anthropic: console.anthropic.com
• Google: aistudio.google.com
• OpenRouter: openrouter.ai

2. Activate Virtual Environment (if not already active)

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

3. Start the Application

# Navigate to the application directory
cd gradio_app

# Run with default model (Claude Sonnet 4)
python app.py

# Or specify a different model
python app.py --model claude-4-sonnet
python app.py --model gemini-2.5-pro
python app.py --model qwen3-coder

Available models by provider:

• OpenAI: gpt-5, gpt-5-mini, gpt-oss
• Anthropic: claude-4-sonnet (default), claude-4-opus, claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001
• Google: gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-3.1-pro, gemini-3.1-flash, gemini-3.1-flash-lite
• OpenRouter: qwen3-coder, qwen3-coder-free, qwen3, gemini-3.1-or, llama-3-70b, deepseek-coder, codestral, glm-5, minimax-m2.7, deepseek-v3.2, etc.

You can also use any OpenRouter model directly by passing its full model ID:

python app.py --model deepseek/deepseek-v3.2
python app.py --model z-ai/glm-5
python app.py --model mistralai/mistral-large-latest

4. Access the Web Interface

1. The application will start and display a URL in the terminal (typically http://localhost:7861/)
2. Open this URL in your web browser