Skip to main content
Glama

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

Related MCP server: FreeCAD MCP Server

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
  1. Install dependencies:

npm install
  1. Build the project:

npm run build
  1. 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

Available Tools

7 tools
boolean_operationB

Perform boolean operations between objects

Inputs: operation (required), object1 (required), object2 (required), result_name.

create_boxC

Create a box/cube in FreeCAD with specified dimensions

Inputs: length (required), width (required), height (required), name.

create_cylinderB

Create a cylinder in FreeCAD

Inputs: radius (required), height (required), name.

create_sphereC

Create a sphere in FreeCAD

Inputs: radius (required), name.

execute_python_scriptB

Execute a custom Python script in FreeCAD

Inputs: script (required).

list_objectsA

List all objects in the current FreeCAD document

Inputs: no named parameters.

save_documentB

Save the current FreeCAD document

Inputs: filename (required), path.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a distinct purpose: creating primitives, boolean operations, scripting, listing, and saving. There is no overlap or ambiguity among them.

    Naming Consistency4/5

    Most tools follow a verb_noun snake_case pattern (e.g., create_box, list_objects). 'boolean_operation' deviates slightly but still uses snake_case and is descriptively clear.

    Tool Count5/5

    With 7 tools, the set is well-scoped for a basic FreeCAD interaction. It covers essential operations without being overwhelming or too sparse.

    Completeness3/5

    The set covers primitive creation, boolean operations, and scripting (which enables arbitrary functionality), but lacks common CAD operations like extrusion, editing, or transformation tools.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to control FreeCAD 3D modeling software, allowing creation and manipulation of 3D objects, execution of Python code, and interaction with FreeCAD's parts library through natural language.
      10
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI to directly call FreeCAD for 3D modeling via the MCP protocol, providing 39 modeling tools including primitive creation, boolean operations, transformations, and export.
      3
      -