FreeCAD MCP Not Working? Fix Claude Connection Errors

October 31, 2026 · FreeCAD + Claude Course (part 7)

▶ Watch on YouTube & subscribe to The Stack Underflow

Between Claude and FreeCAD there’s a cord with several joins: Claude’s list of plugs, the plug itself, the socket inside FreeCAD, and FreeCAD’s answer. Each join fails with its own words. Follow the cord from Claude’s end to FreeCAD, and stop at the first join that fails.

The one-line version: “Connected” only means the plug started. If every request fails, the socket inside FreeCAD is the next thing to check.

Last verified in our lab: 31 October 2026 (FreeCAD 1.1.4; freecad-mcp 0.1.28; Claude Code 2.1.308, with Claude Sonnet 5.5 for the one Claude run; Linux in Docker). The other errors were sent by a test script with no AI that starts the plug with the same line Claude Code uses and sends the same request. Setup is lesson 1.

The words first

  • Plug: freecad-mcp, started by Claude Code through uvx.
  • Socket: the FreeCAD MCP add-on inside FreeCAD; its RPC server listens for the plug’s requests.
  • Port: the numbered door the socket listens on. The plug always uses port 9875.

Stop 1: is the plug on Claude’s list?

Run claude mcp list.

No MCP servers configured. Use `claude mcp add` to add a server.

Cause we filmed: the plug was added without --scope user, so it was saved for one folder only (“to local config”). Fix:

claude mcp remove freecad
claude mcp add --scope user freecad -- uvx freecad-mcp@0.1.28

Claude Code already open when you added it? Type /exit and start claude again.

Stop 2: does the plug start?

freecad: uvx freecad-mcp@0.1.28 - ✘ Failed to connect — ENOENT: Executable not found in $PATH: "uvx"

Cause we filmed: uv was never installed. Fix: install uv (lesson 1’s line), then list again: ✔ Connected.

Stop 3: is the socket on?

“Connected” only means the plug started. Every request then answers:

Error executing tool list_documents

and the plug’s own log says: “Failed to connect to FreeCAD ([Errno 111] Connection refused). Make sure the FreeCAD addon is running.”

Check in order: is FreeCAD open? Is MCP Addon in the workbench list (if not, copy addon/FreeCADMCP into FreeCAD’s Mod folder and restart)? Did you click Start RPC Server (the status bar: “RPC Server started at 127.0.0.1:9875”)? With the 0.1.28 add-on, Auto-Start Server starts it next time.

With Claude (one run): it made three calls, said “Neither error message says why”, and asked us to check that FreeCAD is running and the RPC server is started. After Start RPC Server and “try again”: “FreeCAD has one document open, named hook.” Same session, no restart.

Also tested (not in the video):

  • Another program on port 9875: FreeCAD shows “[MCP] Auto-start failed: [Errno 98] Address already in use”, and the plug’s log says “ProtocolError for localhost:9875/RPC2: 501 Unsupported method (‘POST’)”. Close that program, click Start RPC Server.
  • An old add-on (0.1.24) left in Mod: replies work but start with “Warning: The FreeCAD addon does not report a version, so it is older than freecad-mcp 0.1.28 (protocol 1). Update the addon: …” Replace the add-on folder with the new one and restart FreeCAD. Add-ons 0.1.24 and older are covered by security advisory GHSA-v4pw-r6h3-v75q: update, and keep Auto-Start Server off until you have.

Stop 4: what did FreeCAD answer?

When Claude builds a part, it sends FreeCAD small Python programs. FreeCAD’s error comes back in the reply:

  • Failed to execute code: AttributeError: 'Sketcher.SketchObject' object has no attribute 'Support': since FreeCAD 1.0 the setting is AttachmentSupport. In lesson 3, Claude read this and fixed it itself in both runs.
  • Failed to execute code: OSError: Failed to open file: a save into a folder you may not write to. Save into your own folder.
  • AttributeError: 'NoneType' object has no attribute 'Shape': no object with that name (we asked for Pad001). Ask Claude to list the objects (get_objects).

From the project’s docs, not tested here

  • Windows: EFTYPE / uv_spawn when the Claude app starts the plug. A reported workaround is to launch it through cmd: ["cmd", "/c", "freecad-mcp"].
  • Claude Desktop reads its settings when it starts: quit it fully (from the tray icon), then open it again.

The course

Sources

  • freecad-mcp: the project’s docs (the Windows workaround and Claude Desktop restart above)
  • The lab: the test script, the pre-registered Claude run, logs and the exact text of every error

Change notes

  • 16 Nov 2026: first published, from the lesson’s lab results of 31 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.