How to Connect Claude to FreeCAD (MCP Setup) and Make Your First Part
▶ Watch on YouTube & subscribe to The Stack Underflow
Claude can’t reach into FreeCAD by itself. Two small pieces connect them: an add-on inside FreeCAD that listens for requests (we call it the socket), and a plug that a Claude app starts and that talks to the socket. This lesson installs both, then proves the connection with a part you can measure yourself.
The one-line version: add-on into FreeCAD’s Mod folder, Start RPC Server, install uv, add the plug with one line. Then check the block’s volume in FreeCAD’s own console: 6000.0.
Last verified in our lab: 28 October 2026 (FreeCAD 1.1.4; freecad-mcp 0.1.28; Claude Code 2.1.308 with Claude Sonnet 5.5; Linux in Docker).
The idea first: three pieces
| Piece | What it is | How you know it’s working |
|---|---|---|
| The socket | The FreeCAD MCP add-on, running inside FreeCAD | The status bar says RPC Server started |
| The plug | freecad-mcp, started by the Claude app through uv | claude mcp list says Connected, but that only means the plug starts |
| The Claude app | Claude Code here (Claude Desktop also works) | /mcp lists freecad with 17 tools |
MCP (the Model Context Protocol) is the standard a Claude app uses to talk to plugs like this. A tool is one action the plug offers. uv is a small program that downloads and runs Python tools; it runs the plug.
Why the socket matters: before setup, Claude ran FreeCAD out of sight in its own terminal and saved a file; nothing appeared in the FreeCAD window.
The setup
Claude Code needs a paid Claude plan or an API account.
-
Claude Code: use the install line from Anthropic’s setup page. We added a version number to ours (
bash -s 2.1.308) so the lesson stays the same. If it ends with a setup note and a line to run, run that line. Open a new terminal:claude --version. -
FreeCAD from freecad.org (1.1.4). Ubuntu 24.04 has no apt package: use the AppImage or Flathub.
-
The add-on (the socket): github.com/neka-nat/freecad-mcp at tag v0.1.28, Code, Download ZIP, extract it. Inside, open
addon, thenFreeCADMCP(the folder withInitGui.pydirectly inside). In FreeCAD: View, Panels, Python console, type:print(App.getUserAppDataDir())Open that folder, make a folder called
Modif there isn’t one, and copy the wholeFreeCADMCPfolder into it. From the project’s docs: Windows%APPDATA%\FreeCAD\v1-1\Mod, macOS~/Library/Application Support/FreeCAD/v1-1/Mod. Linux AppImage (what we saw):~/.local/share/FreeCAD/v1-1/Mod. Had an older add-on (0.1.24 or earlier)? Replace the folder (security advisory GHSA-v4pw-r6h3-v75q).Restart FreeCAD, pick MCP Addon in the workbench list, click Start RPC Server. Do that each time you open FreeCAD, or turn on Auto-Start Server.
-
uv: the install line from docs.astral.sh/uv (we pinned 0.13.6). Open a new terminal:
uv --version. -
The plug, typed in the terminal (not in Claude’s chat):
claude mcp add --scope user freecad -- uvx freecad-mcp@0.1.28 claude mcp listThen start
claude(the first time it asks you to sign in) and type/mcp:freecad, 17 tools. First question: “What documents are open in FreeCAD?”
Claude Desktop instead (not filmed; from the MCP docs): Settings, Developer, Edit Config, and inside "mcpServers" add:
"freecad": {"command": "uvx", "args": ["freecad-mcp@0.1.28"]}
Then quit Claude Desktop completely and open it again.
Your first part, by hand
The back plate of the wall hook this course builds. Work it out first: 5 x 20 x 60 = 6,000 mm³.
-
File, New Document; workbench Part; Cube.
-
Click Cube in the tree; in the Property view set Length 5, Width 20, Height 60.
-
Click the block in the tree and type in the Python console:
Gui.Selection.getSelection()[0].Shape.VolumeIt prints 6000.0.
Then with Claude
Open a new document and ask: “Make a block 5 by 20 by 60 millimetres in FreeCAD, then tell me its volume.” Click Claude’s block in the tree and type the same console line, so FreeCAD measures it, not Claude.
What we measured: by hand 6,000.0 mm³, 5 x 20 x 60, Z 0 to 60. Claude used three tools, create_document, create_object (a Part::Box 5, 20, 60) and execute_code (to read the volume): 6,000.0 mm³, same size and place. A replay of Claude’s calls with no AI: 6,000.0.
When it doesn’t work
- Socket off:
claude mcp liststill said Connected; the requests to FreeCAD failed (“Error executing tool”); Claude then built the block in a hidden copy of FreeCAD and said nothing would show in the window. Start RPC Server, ask again: the block appears. - Claude Code already open when the plug was added:
/mcpsays No MCP servers configured; restartclaude.
Lesson 7 covers these failures word for word.
Permissions: what you’re allowing
Claude Code 2.1.308 starts in auto mode: no permission prompt appeared, and a safety check approved each call, including execute_code. execute_code runs any Python with your account’s permissions. To approve each call yourself, press Shift+Tab until the footer no longer shows auto mode (for that session); see Anthropic’s permission modes page. Ctrl+O shows every call Claude made.
The course
- Next: Lesson 2: Sketcher and Pad, by hand vs Claude
- The whole course in order: YouTube playlist
- The lab for this lesson: freecad-course-lab/out/l1
- The same course for SolidCraft: SolidCraft + Claude Course, lesson 1
Sources
- Claude Code setup and permission modes: Anthropic’s docs
- freecad-mcp: the add-on, the plug and their docs (Mod folder paths)
- uv: install line
- The lab: scripts, logs and the logging wrapper’s record of every message to the plug
Change notes
- 16 Nov 2026: first published, from the lesson’s lab results of 28 Oct 2026.
Not affiliated with or endorsed by the FreeCAD project, the freecad-mcp project or Anthropic. Found a mistake? Tell us in the video’s comments and we’ll correct this page.
Found this useful? The deep version lives on YouTube — new breakdowns of how AI dev tools actually work, weekly.
Subscribe on YouTube →Prefer email? Get the free newsletter: one failure, traced step by step, about once a week.