--- title: "FreeCAD MCP Server: Let an AI Model Parts in FreeCAD" url: "https://mcpshelf.co/servers/freecad" description: "Let an assistant create and edit FreeCAD parts, run Python inside FreeCAD and run FEM stress analysis. Addon install, the uvx config and remote safety." updated: "2026-10-27" site: "MCP Shelf" --- # FreeCAD MCP > Lets an assistant build and edit parts in FreeCAD, and run stress analyses on them. ## 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 | | GitHub | https://github.com/neka-nat/freecad-mcp | | Licence | MIT | | PyPI package | [freecad-mcp](https://pypi.org/project/freecad-mcp/) 0.1.28 (25 Oct 2026) | | GitHub stars | 3.1K | | Downloads | 286 a week | | Last commit | 25 Oct 2026 | | Tools | 17 | | Runs on | Your computer | | Install check | Started in our test | | Category | [Design, 3D and games](https://mcpshelf.co/categories/design-and-3d) | **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. ## Tools We listed 17 tools on 27 Oct 2026. 7 only read; the rest can change things or run commands. | Tool | Kind | What it is for | | --- | --- | --- | | `create_document` | changes | Creates a new FreeCAD document. | | `create_object` | changes | Adds an object, such as a box, cylinder or sketch-based feature, to a document. | | `edit_object` | changes | Changes an object's properties. | | `delete_object` | changes | Removes an object. | | `execute_code_async` | runs | Starts a longer Python job in the background and returns a job ID. | | `execute_code_headless` | runs | Runs a script in a separate freecadcmd process, with no GUI. | | `get_async_status` | reads | Checks on a background job and returns any error. | | `execute_code` | runs | Runs Python inside FreeCAD on its main thread. | | `get_view` | reads | Takes a screenshot of the 3D view from a chosen angle. | | `insert_part_from_library` | changes | Inserts a part from the FreeCAD parts library. | | `get_objects` | reads | Lists every object in a document. | | `get_object` | reads | Returns one object's properties. | | `get_parts_list` | reads | Lists the parts in that library. | | `reload_document` | changes | Closes and reopens a saved document to pick up changes made outside FreeCAD. | | `list_documents` | reads | Lists the open documents. | | `get_rpc_status` | reads | Reports whether the addon is reachable and which version it runs. | | `run_fem_analysis` | runs | Runs the CalculiX solver on an existing FEM analysis and returns peak stress and displacement. | ### How clearly it describes its tools 17 of 17 tools have a description and 0 of 17 say whether they change things. The tool list takes at least ~5,000 tokens of context. 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. ## Set it up 1. 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. 2. 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. 3. Add the config below to your client and keep FreeCAD open while you work. ### Claude Desktop Where: claude_desktop_config.json (Settings → Developer → Edit Config) ```json { "mcpServers": { "freecad": { "command": "uvx", "args": [ "freecad-mcp" ] } } } ``` ### Claude Code Where: Your terminal, in the project folder ```bash claude mcp add-json freecad '{"command":"uvx","args":["freecad-mcp"]}' ``` ### Cursor Where: ~/.cursor/mcp.json, or .cursor/mcp.json in a project ```json { "mcpServers": { "freecad": { "command": "uvx", "args": [ "freecad-mcp" ] } } } ``` ### VS Code Where: .vscode/mcp.json in your project ```json { "servers": { "freecad": { "type": "stdio", "command": "uvx", "args": [ "freecad-mcp" ] } } } ``` ### Windsurf Where: ~/.codeium/windsurf/mcp_config.json ```json { "mcpServers": { "freecad": { "command": "uvx", "args": [ "freecad-mcp" ] } } } ``` ### ChatGPT Where: Not supported ChatGPT only connects to remote servers by URL. This one runs on your computer, so use Claude, Cursor or VS Code. 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. ## Settings | Setting | Kind | Required | What it does | | --- | --- | --- | --- | | `--only-text-feedback` | flag | no | Leaves screenshots out of tool results to save tokens. get_view still works. | | `--host` | flag | no | Connects to FreeCAD on another machine instead of localhost. Example: `--host 192.168.1.100` | | `FREECAD_MCP_TOKEN` | env | no | 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 | no | An option in the addon's FreeCAD MCP menu that starts the RPC server whenever FreeCAD opens. | | `Remote Connections` | config | no | 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 ## Good for - Sketching brackets, flanges and enclosures from a description - Making repetitive model changes by asking in plain language - Quick stress checks on a part with FreeCAD FEM ## 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. ## Similar servers | Server | Tools | Runs on | Stars | | --- | --- | --- | --- | | [Excalidraw MCP](https://mcpshelf.co/servers/excalidraw) | 26 | Your computer | 2.6K | | [MCP Unity](https://mcpshelf.co/servers/mcp-unity) | 34 | Your computer | 2K | | [Draw.io MCP Server (lgazo)](https://mcpshelf.co/servers/drawio-lgazo) | 30 | Your computer | 1.5K | | [Blender MCP](https://mcpshelf.co/servers/blender) | 9 | Your computer | 32.4K | ## Questions ### Does it cost anything? No. FreeCAD is free and this project is MIT licensed. ### Which FreeCAD versions work? The project documents folders for FreeCAD 1.0 and 1.1 on Windows, macOS and Linux, including Snap and Flatpak installs. ### Can it run without the FreeCAD window? execute_code_headless runs scripts in freecadcmd, but the other tools talk to the addon inside a running FreeCAD. ### Is execute_code risky? It runs any Python as your user, so treat it like letting the model run scripts on your computer, and keep the addon local. Full docs on GitHub: https://github.com/neka-nat/freecad-mcp --- From [MCP Shelf](https://mcpshelf.co/): A short shelf of MCP servers that are worth installing. Index for agents: https://mcpshelf.co/llms.txt