lucygoodchild/freecad-mcp-server

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