Giters

jhacksman / OpenSCAD-MCP-Server

Devin's attempt at creating an OpenSCAD MCP Server that takes a user prompt and generates a preview image and 3d file.

Repository from Github https://github.comjhacksman/OpenSCAD-MCP-ServerRepository from Github https://github.comjhacksman/OpenSCAD-MCP-Server

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:

openscad-mcp-server/
├── src/
│   ├── main.py                  # Main application
│   ├── main_remote.py           # Remote CUDA MVS server
│   ├── ai/                      # AI integrations
│   │   ├── gemini_api.py        # Google Gemini API for image generation
│   │   └── venice_api.py        # Venice.ai API for image generation (optional)
│   ├── models/                  # 3D model generation
│   │   ├── cuda_mvs.py          # CUDA Multi-View Stereo integration
│   │   └── code_generator.py    # OpenSCAD code generation
│   ├── workflow/                # Workflow components
│   │   ├── image_approval.py    # Image approval mechanism
│   │   └── multi_view_to_model_pipeline.py  # Complete pipeline
│   ├── remote/                  # Remote processing
│   │   ├── cuda_mvs_client.py   # Client for remote CUDA MVS processing
│   │   ├── cuda_mvs_server.py   # Server for remote CUDA MVS processing
│   │   ├── connection_manager.py # Remote connection management
│   │   └── error_handling.py    # Error handling for remote processing
│   ├── openscad_wrapper/        # OpenSCAD CLI wrapper
│   ├── visualization/           # Preview generation and web interface
│   ├── utils/                   # Utility functions
│   └── printer_discovery/       # 3D printer discovery
├── scad/                        # Generated OpenSCAD files
├── output/                      # Output files (models, previews)
│   ├── images/                  # Generated images
│   ├── multi_view/              # Multi-view images
│   ├── approved_images/         # Approved images for reconstruction
│   └── models/                  # Generated 3D models
├── templates/                   # Web interface templates
└── static/                      # Static files for web interface

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.

About

Devin's attempt at creating an OpenSCAD MCP Server that takes a user prompt and generates a preview image and 3d file.

Languages

Language:Python 98.9%Language:OpenSCAD 1.1%Language:Shell 0.1%