How to Connect Claude to FreeCAD (MCP Setup) and Make Your First Part

October 29, 2026 · FreeCAD + Claude Course (part 1)

▶ 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

PieceWhat it isHow you know it’s working
The socketThe FreeCAD MCP add-on, running inside FreeCADThe status bar says RPC Server started
The plugfreecad-mcp, started by the Claude app through uvclaude mcp list says Connected, but that only means the plug starts
The Claude appClaude 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.

  1. 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.

  2. FreeCAD from freecad.org (1.1.4). Ubuntu 24.04 has no apt package: use the AppImage or Flathub.

  3. The add-on (the socket): github.com/neka-nat/freecad-mcp at tag v0.1.28, Code, Download ZIP, extract it. Inside, open addon, then FreeCADMCP (the folder with InitGui.py directly inside). In FreeCAD: View, Panels, Python console, type:

    print(App.getUserAppDataDir())

    Open that folder, make a folder called Mod if there isn’t one, and copy the whole FreeCADMCP folder 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.

  4. uv: the install line from docs.astral.sh/uv (we pinned 0.13.6). Open a new terminal: uv --version.

  5. 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 list

    Then 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³.

  1. File, New Document; workbench Part; Cube.

  2. Click Cube in the tree; in the Property view set Length 5, Width 20, Height 60.

  3. Click the block in the tree and type in the Python console:

    Gui.Selection.getSelection()[0].Shape.Volume

    It 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 list still 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: /mcp says No MCP servers configured; restart claude.

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

Sources

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.