Skip to main content
Glama

OpenSCAD MCP Server

by quellant
GitHub
Python
MIT License
11
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

OpenSCAD MCP Server

MCP Version FastMCP Test Status License

A production-ready Model Context Protocol (MCP) server that provides OpenSCAD 3D rendering capabilities to AI assistants and LLM applications. Built with FastMCP for robust, scalable performance.

🎯 Zero-Installation Execution

Run directly from GitHub without any setup:

uv run --with git+https://github.com/quellant/openscad-mcp.git openscad-mcp

Perfect for MCP clients, CI/CD pipelines, and instant deployment scenarios!

🚀 Quick Start

Zero-Installation Execution with uv

No installation required! Run directly from GitHub:

# Run via script entry point (recommended) uv run --with git+https://github.com/quellant/openscad-mcp.git openscad-mcp # Or run as Python module uv run --with git+https://github.com/quellant/openscad-mcp.git python -m openscad_mcp

Traditional Installation (Optional)

# Clone and run locally git clone https://github.com/quellant/openscad-mcp.git cd openscad-mcp uv run openscad-mcp

Configure with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Option 1: Direct from GitHub (Recommended)

{ "mcpServers": { "openscad": { "command": "uv", "args": ["run", "--with", "git+https://github.com/quellant/openscad-mcp.git", "openscad-mcp"], "env": { "OPENSCAD_PATH": "/usr/bin/openscad" } } } }

Option 2: Local Installation

{ "mcpServers": { "openscad": { "command": "uv", "args": ["run", "openscad-mcp"], "cwd": "/path/to/openscad-mcp", "env": { "OPENSCAD_PATH": "/usr/bin/openscad" } } } }

🔒 Security: --allowedTools Requirement

IMPORTANT: When using the OpenSCAD MCP server with Claude CLI or other MCP clients, you MUST explicitly grant permissions using the --allowedTools flag for security. This prevents unauthorized tool usage and ensures controlled access to server capabilities.

Required Permissions

The OpenSCAD MCP server requires explicit permission for each tool:

  • openscad-mcp:check_openscad - Permission to check OpenSCAD installation

  • openscad-mcp:render_single - Permission to render single views

  • openscad-mcp:render_perspectives - Permission to render multiple perspectives

Example Usage with Claude CLI

# Start the server with uv and grant permissions # (Create mcp-config.json with uv configuration first) # Grant permission for a single tool claude --config mcp-config.json \ --allowedTools openscad-mcp:check_openscad \ "Check if OpenSCAD is installed" # Grant permission for multiple tools claude --config mcp-config.json \ --allowedTools openscad-mcp:check_openscad,openscad-mcp:render_single \ "Render a cube with dimensions 30x30x30" # Grant full permissions for all OpenSCAD tools claude --config mcp-config.json \ --allowedTools openscad-mcp:check_openscad,openscad-mcp:render_single,openscad-mcp:render_perspectives \ "Create a gear model and show it from multiple angles"

Create

{ "mcpServers": { "openscad-mcp": { "command": "uv", "args": ["run", "--with", "git+https://github.com/quellant/openscad-mcp.git", "openscad-mcp"], "env": { "OPENSCAD_PATH": "/usr/bin/openscad" } } } }

Testing with Permissions

Use the provided test script to verify proper permission configuration:

# Run all permission tests ./test_claude_with_permissions.sh all # Test individual tools ./test_claude_with_permissions.sh check # Test check_openscad only ./test_claude_with_permissions.sh single # Test render_single only ./test_claude_with_permissions.sh perspectives # Test render_perspectives only # Launch interactive session with full permissions ./test_claude_with_permissions.sh interactive # Show usage examples ./test_claude_with_permissions.sh examples

✨ Features

  • 🎯 Production-Ready: 100% test success rate with comprehensive integration testing

  • 🔧 Single View Rendering: Render OpenSCAD models from any camera angle with full control

  • 📐 Multiple Perspectives: Generate standard orthographic and isometric views automatically

  • 🎬 Animation Support: Create turntable animations for 360° model visualization

  • ⚡ Async Processing: Non-blocking renders using FastMCP framework for optimal performance

  • 🖼️ Base64 Encoding: Images returned as base64-encoded PNGs for seamless integration

  • ✅ Verified Compatibility: Fully compatible with FastMCP 2.11.3 and Pydantic 2.11.7

📋 Prerequisites

No additional Python packages required when using

📦 Installation

Method 1: Zero-Installation with uv (Recommended)

No installation required! Just run directly:

# Run directly from GitHub - uv handles everything automatically uv run --with git+https://github.com/quellant/openscad-mcp.git openscad-mcp # All dependencies (FastMCP 2.11.3, Pydantic 2.11.7, etc.) are resolved and installed automatically

Method 2: Local Development with uv

# Clone for local development git clone https://github.com/quellant/openscad-mcp.git cd openscad-mcp # Run with uv (installs dependencies automatically) uv run openscad-mcp # Or run as module uv run python -m openscad_mcp

Method 3: Traditional pip Installation

# Only if you can't use uv git clone https://github.com/quellant/openscad-mcp.git cd openscad-mcp pip install -e . python -m openscad_mcp

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# OpenSCAD Configuration OPENSCAD_PATH=/usr/bin/openscad # Path to OpenSCAD executable OPENSCAD_TIMEOUT=30 # Timeout for rendering operations (seconds) # Server Configuration MCP_SERVER_NAME=openscad-mcp MCP_SERVER_VERSION=1.0.0 MCP_SERVER_TRANSPORT=stdio # Transport: stdio, sse, or http # Rendering Configuration MCP_RENDER_MAX_CONCURRENT=4 # Max concurrent renders MCP_RENDER_DEFAULT_WIDTH=800 # Default image width MCP_RENDER_DEFAULT_HEIGHT=600 # Default image height

Configuration File (Optional)

Create config.yaml for advanced configuration:

server: name: "OpenSCAD MCP Server" version: "1.0.0" transport: stdio openscad: timeout: 30 default_color_scheme: "Cornfield" rendering: max_concurrent: 4 default_width: 800 default_height: 600

🛠️ Available MCP Tools

1. render_single

Render a single view of an OpenSCAD model with complete camera control.

Parameters:

Parameter

Type

Required

Description

scad_content

string

No*

OpenSCAD code to render

scad_file

string

No*

Path to .scad file

camera_position

[x,y,z]

No

Camera position (default: [30,30,30])

camera_target

[x,y,z]

No

Look-at point (default: [0,0,0])

camera_up

[x,y,z]

No

Up vector (default: [0,0,1])

image_size

[w,h]

No

Image dimensions in pixels

color_scheme

string

No

OpenSCAD color scheme

variables

dict

No

Variables to pass to OpenSCAD

auto_center

bool

No

Auto-center the model

*Either scad_content or scad_file must be provided

Example Request:

{ "tool": "render_single", "arguments": { "scad_content": "cube([10, 10, 10]);", "camera_position": [30, 30, 30], "image_size": [800, 600], "color_scheme": "Cornfield" } }

Example Response:

{ "success": true, "image": "data:image/png;base64,iVBORw0KGgo...", "metadata": { "width": 800, "height": 600, "render_time": 1.23 } }

2. render_perspectives

Generate multiple standard views of a model (front, back, left, right, top, bottom, isometric).

Parameters:

Parameter

Type

Required

Description

scad_content

string

No*

OpenSCAD code to render

scad_file

string

No*

Path to .scad file

distance

float

No

Camera distance from origin

image_size

[w,h]

No

Image dimensions for each view

variables

dict

No

Variables to pass to OpenSCAD

views

list

No

Specific views to render

Example Request:

{ "tool": "render_perspectives", "arguments": { "scad_file": "model.scad", "views": ["front", "isometric", "top"], "distance": 200, "image_size": [400, 400] } }

3. check_openscad

Verify OpenSCAD installation and get version information.

Parameters:

Parameter

Type

Required

Description

include_paths

bool

No

Include searched paths in response

Example Request:

{ "tool": "check_openscad", "arguments": { "include_paths": true } }

📚 MCP Resources

resource://server/info

Get server configuration and capabilities.

Returns:

  • Server version and status

  • OpenSCAD version and path

  • Rendering capabilities

  • Active operations count

  • Configuration details

🏗️ Architecture

The server implements a clean architecture pattern:

┌─────────────────────────────────────┐ │ MCP Client (Claude) │ └─────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ FastMCP Server (Presentation) │ │ - MCP Protocol Handler │ │ - Tool Decorators │ └─────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Application Layer (Business) │ │ - Rendering Logic │ │ - Parameter Validation │ └─────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Infrastructure Layer (External) │ │ - OpenSCAD CLI │ │ - File I/O Operations │ └─────────────────────────────────────┘

🧪 Testing

The server has achieved 100% test success rate across all integration tests:

# Run comprehensive test suite python comprehensive_test.py # Run MCP tools integration test python test_mcp_tools.py # Run server startup test python test_server_startup.py

See Test Report for detailed results.

🔧 Development

Project Structure

openscad-mcp-server/ ├── src/ │ └── openscad_mcp/ │ ├── __init__.py # Package initialization │ ├── __main__.py # Entry point │ ├── server.py # FastMCP server implementation │ ├── types.py # Pydantic models & types │ └── utils/ │ └── config.py # Configuration management ├── tests/ # Test suite ├── pyproject.toml # Project configuration ├── README.md # This file ├── CHANGELOG.md # Version history ├── API.md # Detailed API documentation └── .env.example # Environment template

Extending the Server

To add new rendering capabilities:

  1. Define parameter types in types.py:

class CustomRenderParams(BaseModel): # Your parameters here pass

  1. Add tool function in server.py:

@mcp.tool async def custom_render(params: CustomRenderParams) -> RenderResult: """Your custom rendering logic""" # Implementation pass

  1. Update documentation in API.md

🐛 Troubleshooting

OpenSCAD Not Found

# Check OpenSCAD installation which openscad # Set environment variable export OPENSCAD_PATH=/path/to/openscad # Or add to .env file OPENSCAD_PATH=/usr/local/bin/openscad

Permission Errors

# Ensure execute permissions chmod +x /path/to/openscad

Rendering Timeouts

Increase timeout in configuration:

export OPENSCAD_TIMEOUT=60 # 60 seconds

FastMCP Compatibility Issues

Ensure correct versions:

pip install fastmcp==2.11.3 pydantic==2.11.7

📈 Performance

  • Single view rendering: ~1-3 seconds (complexity dependent)

  • Multiple perspectives: ~5-10 seconds for 8 views

  • Base64 encoding: < 0.1s overhead

  • Memory footprint: ~50 MB base + 10-20 MB per render

  • Concurrent renders: Up to 4 (configurable)

🚦 Production Status

✅ Ready for Production

  • All tests passing (100% success rate)

  • FastMCP 2.11.3 compatibility verified

  • Comprehensive error handling

  • Async operation support

  • Resource management implemented

  • Documentation complete

📝 License

MIT License - See LICENSE file for details

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

📮 Support

🙏 Acknowledgments

Version: 1.0.0 | Status: Production Ready | Last Updated: 2025-08-25

Deploy Server
-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

Enables AI assistants to render 3D models from OpenSCAD code, generating single views or multiple perspectives with full camera control. Supports animations, custom parameters, and returns base64-encoded PNG images for seamless integration.

  1. 🎯 Zero-Installation Execution
    1. 🚀 Quick Start
      1. Zero-Installation Execution with uv
      2. Traditional Installation (Optional)
      3. Configure with Claude Desktop
    2. 🔒 Security: --allowedTools Requirement
      1. Required Permissions
      2. Example Usage with Claude CLI
      3. Testing with Permissions
    3. ✨ Features
      1. 📋 Prerequisites
        1. 📦 Installation
          1. Method 1: Zero-Installation with uv (Recommended)
          2. Method 2: Local Development with uv
          3. Method 3: Traditional pip Installation
        2. ⚙️ Configuration
          1. Environment Variables
          2. Configuration File (Optional)
        3. 🛠️ Available MCP Tools
          1. 1. render_single
          2. 2. render_perspectives
          3. 3. check_openscad
        4. 📚 MCP Resources
          1. resource://server/info
        5. 🏗️ Architecture
          1. 🧪 Testing
            1. 🔧 Development
              1. Project Structure
              2. Extending the Server
            2. 🐛 Troubleshooting
              1. OpenSCAD Not Found
              2. Permission Errors
              3. Rendering Timeouts
              4. FastMCP Compatibility Issues
            3. 📈 Performance
              1. 🚦 Production Status
                1. 📝 License
                  1. 🤝 Contributing
                    1. 📮 Support
                      1. 🙏 Acknowledgments

                        Related MCP Servers

                        • Sketchfab MCP Server

                          gregkop
                          A
                          security
                          F
                          license
                          A
                          quality
                          Allows interaction with Sketchfab's 3D model platform through Claude or Cursor, enabling users to search, view details, and download 3D models directly from the AI interface.
                          Last updated -
                          4
                          12
                          28

                        • OpenSCAD MCP Server

                          jhacksman
                          -
                          security
                          F
                          license
                          -
                          quality
                          Enables users to generate parametric 3D models from text descriptions or images using multi-view reconstruction and OpenSCAD, with support for AI image generation and remote processing.
                          Last updated -
                          83

                        • mcp-freecad

                          jango-blockchained
                          -
                          security
                          A
                          license
                          -
                          quality
                          This project provides a robust integration between AI assistants and FreeCAD CAD software using the Model Context Protocol (MCP). It allows external applications to interact with FreeCAD through a standardized interface, offering multiple connection methods and specialized tools.
                          Last updated -
                          14
                          MIT License
                          • Linux

                        • Fusion 360 MCP Integration

                          sockcymbal
                          -
                          security
                          F
                          license
                          -
                          quality
                          Enables AI assistants to interact programmatically with Autodesk Fusion 360 for creating parametric 3D models through simple API calls.
                          Last updated -
                          15

                        View all related MCP servers

                        Appeared in Searches

                        New MCP Servers

                        MCP directory API

                        We provide all the information about MCP servers via our MCP API.

                        curl -X GET 'https://glama.ai/api/mcp/v1/servers/quellant/openscad-mcp'

                        If you have feedback or need assistance with the MCP directory API, please join our Discord server