OpenSCAD MCP Server

A Model Context Protocol (MCP) server that enables users to generate 3D models from text descriptions or images, with a focus on creating parametric 3D models using multi-view reconstruction and OpenSCAD.

Features

• AI Image Generation: Generate images from text descriptions using Google Gemini or Venice.ai APIs

• Multi-View Image Generation: Create multiple views of the same 3D object for reconstruction

• Image Approval Workflow: Review and approve/deny generated images before reconstruction

• 3D Reconstruction: Convert approved multi-view images into 3D models using CUDA Multi-View Stereo

• Remote Processing: Process computationally intensive tasks on remote servers within your LAN

• OpenSCAD Integration: Generate parametric 3D models using OpenSCAD

• Parametric Export: Export models in formats that preserve parametric properties (CSG, AMF, 3MF, SCAD)

• 3D Printer Discovery: Optional network printer discovery and direct printing

Architecture

The server is built using the Python MCP SDK and follows a modular architecture:

Installation

1. Clone the repository:

   git clone https://github.com/jhacksman/OpenSCAD-MCP-Server.git cd OpenSCAD-MCP-Server

2. Create a virtual environment:

   python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Install OpenSCAD:

   • Ubuntu/Debian: sudo apt-get install openscad

   • macOS: brew install openscad

   • Windows: Download from openscad.org

5. Install CUDA Multi-View Stereo:

   git clone https://github.com/fixstars/cuda-multi-view-stereo.git cd cuda-multi-view-stereo mkdir build && cd build cmake .. make

6. Set up API keys:

   • Create a .env file in the root directory

   • Add your API keys:

     GEMINI_API_KEY=your-gemini-api-key VENICE_API_KEY=your-venice-api-key # Optional REMOTE_CUDA_MVS_API_KEY=your-remote-api-key # For remote processing

Remote Processing Setup

The server supports remote processing of computationally intensive tasks, particularly CUDA Multi-View Stereo reconstruction. This allows you to offload processing to more powerful machines within your LAN.

Server Setup (on the machine with CUDA GPU)

1. Install CUDA Multi-View Stereo on the server machine:

   git clone https://github.com/fixstars/cuda-multi-view-stereo.git cd cuda-multi-view-stereo mkdir build && cd build cmake .. make

2. Start the remote CUDA MVS server:

   python src/main_remote.py

3. The server will automatically advertise itself on the local network using Zeroconf.

Client Configuration

1. Configure remote processing in your .env file:

   REMOTE_CUDA_MVS_ENABLED=True REMOTE_CUDA_MVS_USE_LAN_DISCOVERY=True REMOTE_CUDA_MVS_API_KEY=your-shared-secret-key

2. Alternatively, you can specify a server URL directly:

   REMOTE_CUDA_MVS_ENABLED=True REMOTE_CUDA_MVS_USE_LAN_DISCOVERY=False REMOTE_CUDA_MVS_SERVER_URL=http://server-ip:8765 REMOTE_CUDA_MVS_API_KEY=your-shared-secret-key

Remote Processing Features

• Automatic Server Discovery: Find CUDA MVS servers on your local network

• Job Management: Upload images, track job status, and download results

• Fault Tolerance: Automatic retries, circuit breaker pattern, and error tracking

• Authentication: Secure API key authentication for all remote operations

• Health Monitoring: Continuous server health checks and status reporting

Usage

1. Start the server:

   python src/main.py

2. The server will start on http://localhost:8000

3. Use the MCP tools to interact with the server:

   • generate_image_gemini: Generate an image using Google Gemini API

     { "prompt": "A low-poly rabbit with black background", "model": "gemini-2.0-flash-exp-image-generation" }

   • generate_multi_view_images: Generate multiple views of the same 3D object

     { "prompt": "A low-poly rabbit", "num_views": 4 }

   • create_3d_model_from_images: Create a 3D model from approved multi-view images

     { "image_ids": ["view_1", "view_2", "view_3", "view_4"], "output_name": "rabbit_model" }

   • create_3d_model_from_text: Complete pipeline from text to 3D model

     { "prompt": "A low-poly rabbit", "num_views": 4 }

   • export_model: Export a model to a specific format

     { "model_id": "your-model-id", "format": "obj" // or "stl", "ply", "scad", etc. }

   • discover_remote_cuda_mvs_servers: Find CUDA MVS servers on your network

     { "timeout": 5 }

   • get_remote_job_status: Check the status of a remote processing job

     { "server_id": "server-id", "job_id": "job-id" }

   • download_remote_model_result: Download a completed model from a remote server

     { "server_id": "server-id", "job_id": "job-id", "output_name": "model-name" }

   • discover_printers: Discover 3D printers on the network

     {}

   • print_model: Print a model on a connected printer

     { "model_id": "your-model-id", "printer_id": "your-printer-id" }

Image Generation Options

The server supports multiple image generation options:

1. Google Gemini API (Default): Uses the Gemini 2.0 Flash Experimental model for high-quality image generation

   • Supports multi-view generation with consistent style

   • Requires a Google Gemini API key

2. Venice.ai API (Optional): Alternative image generation service

   • Supports various models including flux-dev and fluently-xl

   • Requires a Venice.ai API key

3. User-Provided Images: Skip image generation and use your own images

   • Upload images directly to the server

   • Useful for working with existing photographs or renders

Multi-View Workflow

The server implements a multi-view workflow for 3D reconstruction:

1. Image Generation: Generate multiple views of the same 3D object

2. Image Approval: Review and approve/deny each generated image

3. 3D Reconstruction: Convert approved images into a 3D model using CUDA MVS

   • Can be processed locally or on a remote server within your LAN

4. Model Refinement: Optionally refine the model using OpenSCAD

Remote Processing Workflow

The remote processing workflow allows you to offload computationally intensive tasks to more powerful machines:

1. Server Discovery: Automatically discover CUDA MVS servers on your network

2. Image Upload: Upload approved multi-view images to the remote server

3. Job Processing: Process the images on the remote server using CUDA MVS

4. Status Tracking: Monitor the job status and progress

5. Result Download: Download the completed 3D model when processing is finished

Supported Export Formats

The server supports exporting models in various formats:

• OBJ: Wavefront OBJ format (standard 3D model format)

• STL: Standard Triangle Language (for 3D printing)

• PLY: Polygon File Format (for point clouds and meshes)

• SCAD: OpenSCAD source code (for parametric models)

• CSG: OpenSCAD CSG format (preserves all parametric properties)

• AMF: Additive Manufacturing File Format (preserves some metadata)

• 3MF: 3D Manufacturing Format (modern replacement for STL with metadata)

Web Interface

The server provides a web interface for:

• Generating and approving multi-view images

• Previewing 3D models from different angles

• Downloading models in various formats

Access the interface at http://localhost:8000/ui/

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.