What is Freecad Mcp Server

freecad-mcp-server is a Model Context Protocol (MCP) server that allows AI assistants to interact with FreeCAD for 3D modeling and CAD operations.

Use cases

Use cases include automating the creation of 3D models, integrating AI-driven design processes, and enhancing productivity in CAD workflows.

How to use

To use freecad-mcp-server, first install FreeCAD and Node.js. Clone the repository, install dependencies, build the project, and run the server using ‘npm start’. Configure your MCP client to connect to the server.

Key features

Key features include basic geometry creation (boxes, cylinders, spheres), boolean operations (union, cut, common), document management (saving documents and listing objects), custom script execution in FreeCAD context, and cross-platform support (Windows, macOS, Linux).

Where to use

freecad-mcp-server can be used in fields such as architecture, engineering, product design, and any domain requiring 3D modeling and CAD operations.

FreeCAD MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with FreeCAD for 3D modeling and CAD operations.

Features

• Basic Geometry Creation: Create boxes, cylinders, spheres with specified dimensions
• Boolean Operations: Perform union, cut, and common operations between objects
• Document Management: Save documents and list objects
• Custom Script Execution: Execute arbitrary Python scripts in FreeCAD context
• Cross-Platform: Supports Windows, macOS, and Linux

Prerequisites

1. FreeCAD Installation: Install FreeCAD from freecad.org
2. Node.js: Version 18 or higher
3. TypeScript: For development

Installation

1. Clone this repository:

git clone https://github.com/lucygoodchild/freecad-mcp-server.git
cd freecad-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Configure FreeCAD path (if needed):
   • The server attempts to auto-detect FreeCAD installation
   • Default paths:
     • Windows: C:\Program Files\FreeCAD 0.21\bin\FreeCAD.exe
     • macOS: /Applications/FreeCAD.app/Contents/MacOS/FreeCAD
     • Linux: /usr/bin/freecad

Usage

Running the Server

npm start

Claude Desktop

Add the following to your MCP client configuration (~/Library/Application Support/Claude/claude_desktop_config.json):
{
“mcpServers”: {
“freecad-mcp-server”: {
“command”: “node”,
“args”: [“/path/to/free-cad-mcp/build/index.js”]
}
}
}
Make sure to replace “/path/to/free-cad-mcp/build/index.js” with the actual path and to restart Claude once you have made the changes

Available Tools

create_box

Create a rectangular box with specified dimensions.

{
  "name": "create_box",
  "arguments": {
    "length": 50,
    "width": 30,
    "height": 20,
    "name": "MyBox"
  }
}

create_cylinder

Create a cylinder with specified radius and height.

{
  "name": "create_cylinder",
  "arguments": {
    "radius": 10,
    "height": 50,
    "name": "MyCylinder"
  }
}

create_sphere

Create a sphere with specified radius.

{
  "name": "create_sphere",
  "arguments": {
    "radius": 15,
    "name": "MySphere"
  }
}

boolean_operation

Perform boolean operations between two objects.

{
  "name": "boolean_operation",
  "arguments": {
    "operation": "union",
    "object1": "Box",
    "object2": "Cylinder",
    "result_name": "Combined"
  }
}

Operations: union, cut, common

save_document

Save the current FreeCAD document.

{
  "name": "save_document",
  "arguments": {
    "filename": "my_model.FCStd",
    "path": "/path/to/save"
  }
}

list_objects

List all objects in the current document.

{
  "name": "list_objects",
  "arguments": {}
}

execute_python_script

Execute custom Python script in FreeCAD context.

{
  "name": "execute_python_script",
  "arguments": {
    "script": "box = doc.addObject('Part::Box', 'CustomBox')\nbox.Length = 100"
  }
}

Integration with AI Assistants

This server implements the Model Context Protocol, making it compatible with MCP-enabled AI assistants. The AI can:

1. Generate 3D Models: Create complex geometries by combining basic shapes
2. Parametric Design: Modify dimensions and parameters based on requirements
3. Assembly Creation: Build multi-part assemblies using boolean operations
4. Design Automation: Execute complex modeling workflows through scripting

Example AI Interactions

• “Create a bearing housing with a 20mm inner diameter and 40mm outer diameter”
• “Make a threaded bolt with M6 threading, 50mm long”
• “Design a simple bracket to hold two 10mm rods 30mm apart”

Development

Project Structure

src/
  index.ts          # Main server implementation
build/              # Compiled JavaScript output
package.json        # Dependencies and scripts
tsconfig.json       # TypeScript configuration

Building

npm run build

Development Mode

npm run dev

Troubleshooting

FreeCAD Not Found

• Verify FreeCAD is installed and accessible from command line
• Update the freecadPath in the server constructor if needed
• Check that the FreeCAD executable has proper permissions

Script Execution Errors

• Ensure FreeCAD Python environment has required modules
• Check script syntax - Python scripts are executed in FreeCAD’s Python interpreter
• Use list_objects to verify object names before boolean operations