You can run an MCP server that lets AI assistants interact with FreeCAD through a standardized interface. This server exposes multiple connection methods, supports a variety of tool providers, and lets you wire AI workflows directly into FreeCAD to create, modify, and export geometry. It is designed to be practical for developers and designers who want reliable automation and scripting capabilities inside FreeCAD workflows.

How to use

Install and run the MCP server to enable AI-assisted FreeCAD operations. You can connect with a client that supports MCP and start creating documents, drawing shapes, transforming geometry, and exporting models. The server provides multiple connection backends, so you can choose the integration method that best fits your setup. Start with a default server and adjust the configuration to use a preferred mode or a custom config file. You can then issue tool calls from your MCP client to perform primitive creation, model manipulation, and document management within FreeCAD.

How to install

Prerequisites: ensure you have Python installed (3.8+ is recommended) and have access to the command line. You may also need Git to clone the repository.

Step by step commands you will use to get the MCP server running:

git clone https://github.com/jango-blockchained/mcp-freecad.git

cd mcp-freecad

pip install -r requirements.txt

python mcp_server.py

Start with FastMCP mode for a lightweight setup

python mcp_server.py --mode fastmcp

Or run with a custom config and enable debug logging

python mcp_server.py --config my_config.json --debug

Configuration and usage notes

The server supports a configurable set of options to tailor how FreeCAD is accessed and how tools are exposed. You can enable primitives, model manipulation, and export/import features, and you can point the server at your FreeCAD installation. If you need to start with a minimal setup, begin with the default configuration and progressively enable additional tool categories as your automation needs grow.

Available tools

create_document

Create a new FreeCAD document with a specified name.

list_documents

List all open FreeCAD documents.

list_objects

List objects contained in a document.

create_box

Create a 3D box primitive with specified length, width, and height.

create_cylinder

Create a cylinder primitive with specified radius and height.

create_sphere

Create a sphere primitive with a given radius.

transform

Apply translation, rotation, or scaling to objects.

boolean_operation

Perform union, difference, or intersection between objects.

fillet_edge

Apply fillets to edges to round corners.

chamfer_edge

Chamfer edges for smoother transitions.

mirror

Mirror objects across a plane.

scale

Scale objects uniformly or non-uniformly.

export_stl

Export a selected object or document to STL format.

create_box_geometry

Alias for creating box primitives with detailed parameters.