Gnucleus Text To CAD MCP Server

What is Gnucleus Text To CAD MCP Server about?

The server provides a Model Context Protocol (MCP) endpoint that accepts a single text input and returns a CAD model generated by gNucleus’s AI. It works with any MCP‑compatible client (e.g., Claude Desktop, custom scripts) to turn descriptions like “draw a block with length=80mm” into a 3‑D model hosted on gNucleus.

How to use Gnucleus Text To CAD MCP Server?

1. Clone the repo and set up a Python 3.7+ virtual environment.
2. Create a .env file with GNUCLEUS_HOST and GNUCLEUS_API_KEY (enterprise users also add GNUCLEUS_ORG_ID).
3. Install dependencies via pip install -r requirements.txt.
4. Start the server with python main.py or test it using the MCP inspector: npx @modelcontextprotocol/inspector python3 main.py.
5. Configure your MCP client (e.g., Claude Desktop) to point to the running server and call the text_to_cad tool.

Key features of Gnucleus Text To CAD MCP Server

• Single MCP tool: text_to_cad(input: str)
• Supports both part and assembly generation
• Multilingual prompts (English works best, but Chinese, Spanish, etc., are accepted)
• Returns design spec, key parameters, description, and a temporary 24‑hour shared 3‑D viewer URL
• Simple environment setup with optional virtual‑env configuration

Use cases of Gnucleus Text To CAD MCP Server

• Rapid prototyping for mechanical engineers who want to materialize ideas without manual CAD modeling
• Integration into AI assistants (Claude, ChatGPT) to enable on‑the‑fly CAD generation during conversations
• Educational tools that illustrate geometry concepts by converting textual descriptions into visual models
• Automation pipelines that generate standard components (bolts, gears, flanges) from a parts list

FAQ from the Gnucleus Text To CAD MCP Server

Q: Which Python version is required?
A: Python 3.7 or newer.

Q: Do I need a gNucleus account?
A: Yes. Sign up at https://gnucleus.ai and create an API key (personal or team).

Q: How is authentication handled?
A: The server reads GNUCLEUS_API_KEY from the .env file and passes it to the gNucleus API.

Q: Can I download the generated CAD file?
A: Direct download isn’t supported yet. Open the shared viewer URL, log in to gNucleus, and download the model from there.

Q: What if the model looks incomplete?
A: Try the same prompt on the gNucleus web UI and download the file to inspect it; often the issue is a partial generation that can be resolved by re‑prompting.

Q: How do I run the server on a remote machine?
A: Ensure the .env file is secured, expose the desired port, and start python main.py in a background process or container.

gNucleus Text To CAD MCP server

gNucleus is a Generative AI platform that transforms text and images into editable CAD models.

This repository contains the gNucleus Text-To-CAD MCP server, which connects to the gNucleus API. It allows MCP clients to generate CAD parts or assemblies from text input using gNucleus’s GenAI models.

Prerequisites

• Python 3.7+
• gNucleus Developer Accounts with:
  • gNucleus API key

Setup

1. Clone this repository

2. Create and activate a virtual environment (recommended):

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

3. Install dependencies:

   pip install -r requirements.txt
   

4. Create a .env file in the root directory with the following variables:

   Invidisual User

   GNUCLEUS_HOST="genai.gnucleus.ai"
   GNUCLEUS_API_KEY=<your-personal-api-key>
   

   Enterprise User

   GNUCLEUS_HOST="genai.gnucleus.ai"
   GNUCLEUS_API_KEY=<your-team-key>
   GNUCLEUS_ORG_ID=<your-team-id>
   

Obtaining gNucleus API KEY

1. gNucleus Account: sign-up on https://gnucleus.ai/
2. API KEY: Create a personal access token in gNucleus:
   • Go to User Profile (click your user icon in the top right)
   • Go to "Account"
   • Click "Generate New API Key" to generate a new API KEY
   • Each account start with 200 free API credit

Running the Server

Start the MCP server:

python main.py

You can test the MCP server using the inspector by running

npx @modelcontextprotocol/inspector python3 main.py

Available MCP Tools

The following MCP tools are available:

• text_to_cad(input: str) - Generate CAD from input

Example Prompt with LLMs

When used with LLMs that support the MCP protocol, this server enables natural language interaction with gNucleus:

1. Text to CAD

• "draw a block in CAD"
• "draw a block with length=80mm, width=40mm, height=20mm in CAD"
• "draw a spur gear shaft in CAD"
• "draw a spur gear shaft with number_teeth=20 in CAD"
• "draw an elbow flange in CAD"
• "draw an elbow flange with number_bolt_holes=4 in CAD"

i18n support: You can use any language as the prompt, in general english works better than other languages, but it should work in general.

• Chinese: "在CAD中绘制一个大小为10mm的方块"
• Spanish: "Dibuja un bloque cuadrado de 10 mm en CAD"

2. Text to Assembly

• "generate a tapered roller bearing using text-to-cad tool"
• "draw a differential gear box in CAD"

3. Result CAD Display

The generated result include the design spec with Key Parameter, Description and a shared URL with 3D display viewer. The shared URL will be expired in 24 hrs.

Claude Desktop Setup

1. Add or update the Claude Desktop configuration file(claude_desktop_config.json):

virtual python environment

If you use virtual python enviroment, use this config:

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

global python environment

If you use global python enviroment and also installed the requirments.txt into your global python enviroment, use this config

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

2. Save the file and restart Claude Desktop

You should see the gNucleus Text-To-CAD tools in Claude

3. Chat with Claude to generate the CAD model

Chat with Claude and add "in CAD" in each prompt or tell Claude to use "text-to-cad tools"can help Claude to trigger the Text-To-CAD tool better.

The generated result include the design spec with Key Parameter, Description and a shared link with 3D display viewer. The shared URL will be expired in 24 hrs. If Claude didn't output the shared URL in the chat message, you can ask Claude to always output the shared URL.

Click the shared URL, it will display the CAD model in gNucleus 3D viewer, you can

• Rotate by holding the left mouse button
• Pan by holding the right mouse button
• Zoom using the middle mouse button

Example 1: Text To CAD Part

• Input and CAD Part design spec

• CAD Part in 3D viewer

Example 2: Text To CAD Assembly

• Input and CAD Assembly design spec

• CAD Assembly in 3D viewer

Note: Downloading CAD models from the viewer is not yet supported. To download the model, please log in to https://gnucleus.ai and try the same prompt using the full feature set.

Troubleshooting

CAD Model

If the CAD model looks incorrect or only partially generated, try logging in at https://gnucleus.ai, enter the same prompt, and download the CAD file (e.g., FreeCAD format). Then open it in your CAD software(e.g. FreeCAD ). This issue is often caused by incomplete generation of CAD features within the part.

You can also report a bug or contact us with the model link and prompt at https://gnucleus.ai/contact.

Security Considerations

• Secure your .env file and never commit it to github
• Run this server in a secure environment