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):

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