FreeCAD MCP

Lets an assistant build and edit parts in FreeCAD, and run stress analyses on them.

Started in our test
★ 3.1K GitHub stars
286 downloads a week
Last commit 25 Oct 2026

At a glance

FreeCAD is the free, open source parametric CAD program. This project by neka-nat has two halves: an addon that runs a small RPC server inside FreeCAD, and an MCP server your client starts. With both running, the model can create documents and objects, change their properties, insert parts from the FreeCAD library, take a screenshot of the view to check its work, and run a CalculiX FEM analysis on a part.

It can also run any Python code inside FreeCAD, which is what makes it powerful and what makes it worth care: that code runs with your user account. By default the addon only listens on your own machine. If you open it to the network, set an auth token and allow only trusted addresses.

Made by: neka-nat and contributors
Licence: MIT
Latest version: 0.1.28 (25 Oct 2026)
PyPI package: freecad-mcp
GitHub stars: 3.1K
Downloads: 286 a week
Last commit: 25 Oct 2026
Tools: 17
Runs on: Your computer

Our check: We ran this exact config on 27 Oct 2026: it started and answered with 17 tools. The shared database gave "npx freecad-mcp", an npm package by someone else. This project publishes freecad-mcp on PyPI and runs with uvx.

What's in the pod: its tools

We found 17 tools when we started it on 27 Oct 2026. 7 only read. The rest can change things, so keep your app's "ask before each tool call" setting on for them.

Runs commands4 tools · Can start programs or run code.

Tool	What it is for
`execute_code`	Runs Python inside FreeCAD on its main thread.
`execute_code_async`	Starts a longer Python job in the background and returns a job ID.
`execute_code_headless`	Runs a script in a separate freecadcmd process, with no GUI.
`run_fem_analysis`	Runs the CalculiX solver on an existing FEM analysis and returns peak stress and displacement.

Changes things6 tools · Can create, edit, send or delete.

Tool	What it is for
`create_document`	Creates a new FreeCAD document.
`create_object`	Adds an object, such as a box, cylinder or sketch-based feature, to a document.
`delete_object`	Removes an object.
`edit_object`	Changes an object's properties.
`insert_part_from_library`	Inserts a part from the FreeCAD parts library.
`reload_document`	Closes and reopens a saved document to pick up changes made outside FreeCAD.

Only reads7 tools · Looks things up and changes nothing.

Tool	What it is for
`get_async_status`	Checks on a background job and returns any error.
`get_object`	Returns one object's properties.
`get_objects`	Lists every object in a document.
`get_parts_list`	Lists the parts in that library.
`get_rpc_status`	Reports whether the addon is reachable and which version it runs.
`get_view`	Takes a screenshot of the 3D view from a chosen angle.
`list_documents`	Lists the open documents.

Grouped and described by us. The README on GitHub lists the inputs each tool takes.

How clearly it describes its tools to your assistant

Tools with a description: 17 of 17
Say if they change things: 0 of 17
Context it takes, at least: ~5,000 tokens

No tool says whether it only reads or can change things, so your client treats them all alike: keep approvals on. The tool list is large: switch off the tools you do not use if your client allows it.

From the tool list it sent us. The token figure counts names, descriptions and input names; the full schemas your client loads add more.

Set it up

Download the repository and copy its addon/FreeCADMCP folder into the Mod folder of your FreeCAD user data (for example ~/.local/share/FreeCAD/Mod on Debian), then restart FreeCAD.
Switch to the MCP Addon workbench and click Start RPC Server. Tick Auto-Start Server in the FreeCAD MCP menu to skip this next time.
Add the config below to your client and keep FreeCAD open while you work.

Pick your app for the exact snippet and where it goes.

Where it goes: claude_desktop_config.json (Settings → Developer → Edit Config)

Claude Desktop

{
  "mcpServers": {
    "freecad": {
      "command": "uvx",
      "args": [
        "freecad-mcp"
      ]
    }
  }
}

Where it goes: Your terminal, in the project folder

Claude Code

claude mcp add-json freecad '{"command":"uvx","args":["freecad-mcp"]}'

Where it goes: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

Cursor

{
  "mcpServers": {
    "freecad": {
      "command": "uvx",
      "args": [
        "freecad-mcp"
      ]
    }
  }
}

Where it goes: .vscode/mcp.json in your project

VS Code

{
  "servers": {
    "freecad": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "freecad-mcp"
      ]
    }
  }
}

Where it goes: ~/.codeium/windsurf/mcp_config.json

Windsurf

{
  "mcpServers": {
    "freecad": {
      "command": "uvx",
      "args": [
        "freecad-mcp"
      ]
    }
  }
}

Add "--only-text-feedback" to leave out screenshots and save tokens. To reach FreeCAD on another machine, pass "--host" with its address and set FREECAD_MCP_TOKEN to the token set in the addon.

New to this? See the setup guides for Claude Code, Cursor, Claude Desktop and ChatGPT.

Settings

Names are exactly as the project spells them. Required ones are marked.

Setting	What it does
`--only-text-feedback`Command line flag	Leaves screenshots out of tool results to save tokens. get_view still works.
`--host`Command line flag	Connects to FreeCAD on another machine instead of localhost.`--host 192.168.1.100`
`FREECAD_MCP_TOKEN`Environment variable	The auth token you set in the addon. Needed once the addon requires one; safer than --auth-token, which shows in the process list.
`Auto-Start Server`Config	An option in the addon's FreeCAD MCP menu that starts the RPC server whenever FreeCAD opens.
`Remote Connections`Config	An addon option that listens on all interfaces, limited to the addresses in Allowed IPs. Off by default.

What it can touch

It can read

Open FreeCAD documents and their objects
Screenshots of the 3D view
The FreeCAD parts library

It can change

Documents and objects in FreeCAD
Anything Python can touch with your user's rights, through execute_code

Safer setup: Keep Remote Connections off so only your own machine can reach the addon. If you need remote access, set an auth token and use an SSH tunnel on untrusted networks. Save your work first, since execute_code can change or close documents.

Before you start

FreeCAD with the FreeCAD MCP addon installed
uv, for uvx
Python 3.12 or newer, which uvx can fetch for you

If it does not work

Every tool reports that it cannot connect: FreeCAD must be open with the RPC server started from the MCP Addon workbench. Tick Auto-Start Server to have it start each time.
The MCP Addon workbench does not appear: The FreeCADMCP folder must sit directly in FreeCAD's Mod folder, whose location depends on your system and FreeCAD version. Restart FreeCAD after copying it.
Long scripts or FEM runs time out: Use execute_code_async or execute_code_headless for long jobs, and raise your client's tool timeout.
Answers use a lot of tokens: Start the server with --only-text-feedback, or ask for include_screenshot false on intermediate steps.

Peas in a pod: similar servers

How FreeCAD MCP lines up against other design, 3d and games servers on the shelf.

Server	Tools	Runs on	Licence	Stars
FreeCAD MCP	17	Your computer	MIT	3.1K
Excalidraw MCP	26	Your computer	MIT	2.6K
Blender MCP	9	Your computer	MIT	32.4K
Framelink Figma MCP	2	Your computer	MIT	16.1K
Talk to Figma	40	Your computer	–	7.1K