Overview

The gNucleus Text-to-CAD MCP server connects Model Context Protocol (MCP) clients and LLMs to the gNucleus generative-CAD API. It exposes a lightweight MCP-compatible endpoint that receives natural language prompts and returns generated CAD parts or assemblies produced by gNucleus GenAI models. The server is intended for developers who want to wire CAD generation into chat interfaces, personal assistants, or automation pipelines without building CAD pipelines from scratch.

This repository implements the MCP server in Python, handles authentication with the gNucleus API, and exposes a single tool that MCP-aware LLMs can call to request CAD outputs. Outputs include a design specification (key parameters and description) and a shareable 3D viewer URL created by gNucleus (the share link expires after 24 hours). The server is useful for prototyping text-driven CAD workflows, integrating with desktop LLM clients, and enabling programmatic CAD generation from conversational agents.

Features

MCP-compatible server that maps LLM tool calls to gNucleus CAD generation
Single tool API: text_to_cad(input: string) — generate a CAD part or assembly from text
Lightweight Python implementation (3.7+) with simple environment-based configuration
Support for individual and enterprise (team/org) gNucleus API keys
Example configuration for running inside Claude Desktop or other MCP clients
Returns design spec and a shareable 3D viewer URL for quick inspection

Prerequisites

Python 3.7 or later
gNucleus developer account and API key (personal or team key)
Internet access to reach the gNucleus host (default: genai.gnucleus.ai)

Installation / Configuration

Clone, create a virtual environment, install dependencies, and add environment variables:

# Clone the repo
git clone https://github.com/gNucleus/text-to-cad-mcp.git
cd text-to-cad-mcp

# Create & activate virtual environment (recommended)
python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows
# .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Create a .env file in the repository root with the required configuration. Example values:

# Individual user
GNUCLEUS_HOST="genai.gnucleus.ai"
GNUCLEUS_API_KEY="your-personal-api-key"

Enterprise (team) configuration:

# Enterprise user
GNUCLEUS_HOST="genai.gnucleus.ai"
GNUCLEUS_API_KEY="your-team-api-key"
GNUCLEUS_ORG_ID="your-team-id"

Quick reference for environment variables:

Variable	Required (Individual)	Required (Enterprise)	Description
GNUCLEUS_HOST	Yes	Yes	gNucleus API host (default provided)
GNUCLEUS_API_KEY	Yes	Yes	Personal or team API key
GNUCLEUS_ORG_ID	No	Yes (if using org key)	Team/organization identifier

Start the MCP server:

python main.py

Validate with the MCP inspector (requires Node/npm):

npx @modelcontextprotocol/inspector python3 main.py

Available Tools

text_to_cad(input: string) -> Generates a CAD part or assembly from a natural language prompt and returns:
- Design spec (key parameters, description)
- Shared 3D viewer URL (expires in 24 hours)
- Metadata about the generated model (when provided)

The tool is designed to be called by MCP-aware LLMs or an MCP client that follows the Model Context Protocol.

Use Cases

Chat-driven CAD prototyping: Integrate with a conversational agent (e.g., Claude Desktop) so a user can say “draw a block with length=80mm, width=40mm, height=20mm in CAD” and receive a viewer link and spec.
Text-to-assembly: Ask for multi-part assemblies (e.g., “generate a tapered roller bearing”) and receive an assembled CAD result.
Translation-friendly prompts: The server accepts prompts in multiple languages (English generally performs best), e.g., Chinese: “在CAD中绘制一个大小为10mm的方块”.
Automated generation pipelines: Use the MCP endpoint in scripts or CI flows to auto-generate part geometry from requirement text.

Example prompts:

“draw a spur gear shaft with number_teeth=20 in CAD”
“draw an elbow flange with number_bolt_holes=4 in CAD”
“generate a differential gearbox assembly in CAD”

Integration Example: Claude Desktop

Add the MCP server to your Claude Desktop config (use absolute paths). Example for virtualenv:

{
  "mcpServers": {
    "gnucleus": {
      "command": "/ABSOLUTE/PATH/text-to-cad-mcp/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/text-to-cad-mcp/main.py"],
      "workingDirectory": "/ABSOLUTE/PATH/text-to-cad-mcp",
      "env": {
        "GNUCLEUS_HOST": "genai.gnucleus.ai",
        "GNUCLEUS_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

After restarting Claude Desktop, the gNucleus Text-to-CAD tool will be available for prompts prefixed with “in CAD” or explicitly invoked by the assistant.

Troubleshooting & Security

If CAD appears incomplete, retry the same prompt on https://gnucleus.ai and download the model to inspect in a CAD application (e.g., FreeCAD). Partial outputs are usually generation artifacts.
Secure your .env and never commit API keys to source control.
Run this server in a trusted environment and rotate API keys if they are exposed.
For bugs or support, use the gNucleus contact channels or open an issue on the GitHub repository.

Resources

Repository: https://github.com/gNucleus/text-to-cad-mcp
gNucleus: https://gnucleus.ai
Contact/support: https://gnucleus.ai/contact

gNucleus Text-to-CAD MCP Server