‹Addon› freecad-mcp-bridge

[zewpo]

🔌 𝗥𝗲𝗽𝗼𝘀𝗶𝘁𝗼𝗿𝘆

https://github.com/CREATeNG/freecad-mcp-bridge

📑 𝗡𝗼𝘁𝗲𝘀

Hi maintainers,

This addon is an autoloading global module that allows AI assistants (like Antigravity, Claude, Cursor, etc.) to script and control FreeCAD sessions with Python code, via the Model Context Protocol (MCP) using a self-contained local named-pipe/socket bridge.

Thank you!

[zewpo]

Update: Index PR opened for initial listing.

Index PR: #73

This adds the freecad-mcp-bridge entry to Data/Index.json with install ref v0.1.14 (tag-pinned release workflow; main remains development).

• Repository: https://github.com/CREATeNG/freecad-mcp-bridge
• Tag / git_ref: v0.1.14
• Zip URL: https://github.com/CREATeNG/freecad-mcp-bridge/archive/refs/tags/v0.1.14.zip

The PR diff is Data/Index.json only (minimal hunk). "curated": false on this first listing — happy for maintainers to set curated as appropriate on review/merge.

v0.1.14 is the first Index-ready ship with verified install-from-tag on Linux/macOS/Windows before release.

Thanks again for review.

[zewpo]

⚠️ Superseded — see the updates below. This described the original local-socket design. Since we cannot include binaries, this addon has since moved to an in-process, loopback-only HTTP server (the named socket and the prebuilt binaries are both gone). Current security details: README § Privacy & security.

Security / connections (for review)

The in-FreeCAD bridge listens on a local socket only (named pipe / UNIX domain socket) when the user turns it on via the toolbar; it is off by default each session. The addon does not use any network connections or collect telemetry.

While enabled, any local process that can reach the socket could send Python to the open session — same trust model as running macros. Users should only enable the bridge when they trust other software on that machine.

The optional bundled MCP server is a local process (stdio to a local MCP client, local socket to the bridge). The MCP client also runs locally; if it talks to an external AI service, that is configured in the client — not by FreeCAD or this addon.

More detail: README § Privacy & connections and SECURITY.md.

[zewpo]

UI / global toolbar (for review — feedback welcome)

Index Qualities recommend confining UI side effects to an addon’s own workbench. This addon is packaged as <other> (not a workbench): it adds a small MCP Bridge toolbar with a single On/Off toggle so users can enable the local socket from whichever workbench they are modeling in.

Implementation notes:

• The toolbar is injected at startup and re-shown after workbench changes via WorkbenchManipulator — so the toggle stays available without nesting the bridge inside every workbench.
• It does not hide, remove, or modify FreeCAD core toolbars/menus or other addons; it only adds this one toolbar and command.
• The bridge still starts only when the user toggles it on; import does not open the socket.

We chose a global toggle because AI/script access is session-wide (the open FreeCAD document/window), not tied to one workbench. If maintainers prefer a narrower pattern (e.g. scoped to a dedicated workbench or a different injection approach), we are happy to adjust — please share what you would recommend.

[zewpo]

Design context (for reviewers)

MCP Bridge gives AI tools access to the user's open FreeCAD session. A flexible, light, and direct bridge by design. AI tools work with the session itself, using the full FreeCAD Python API — in whatever part of FreeCAD the user is working — rather than through a catalog of predefined AI commands that only covers what has been wrapped and must be kept updated as FreeCAD changes.

In practice we have not seen a need for a maintained catalog of AI-specific tools. We have found that AI agents work well using the FreeCAD Python API.

Robust MCP Bridge and freecad-mcp take a different approach: common tasks are exposed as named AI commands instead. By contrast, this listing is intentionally minimal: a flexible, lightweight bridge to the session, not a maintained tool catalog.

[chennes]

We generally don't add Addons to the Index when they ship with pre-built binaries -- those will need to be removed in order to have this addon considered. The addon also appears to use exec() on untrusted code (in bridge.py) -- you should strongly consider using QLocalServer.setSocketOptions(QLocalServer.UserAccessOption), and possibly also adding a per-session shared secret (though that's covering a bit of a marginal attack vector).

[zewpo]

Update — proposed direction following your review

Thank you for the feedback. We've done a review and want to share the proposed direction before implementing — in case you have further thoughts.

Proposed direction: Addon-Hosted MCP Server

The MCP server moves inside the FreeCAD process, running on FreeCAD's bundled Python (3.11, confirmed on all platforms). No binary ships with the addon; no user-side dependencies beyond the addon itself. Rather than removing the binary and asking users to install system Python and the mcp package, this keeps setup frictionless.

On your specific points:

Prebuilt binaries — resolved. The Rust MCP server and bin/ directory are removed entirely under this approach.

UserAccessOption — the local socket bridge is replaced by the in-process server in this architecture, so this fix no longer applies here. Noted for any future direction that retains the socket.

Per-session shared secret — noted; agree it covers a marginal vector. The in-process server uses a loopback TCP port (user-toggled, loopback only, no outbound data) rather than a named socket, so the threat model differs slightly — though as with the socket, any local process could reach the port while it's open.

TCP port and Index compliance — we've reviewed the Index Qualities page and believe a user-toggled, loopback-only port satisfies the transparency, deferred activation, and no-data-without-consent requirements. We'd welcome confirmation, or a flag if you see a concern we've missed.

update - next comment:

[zewpo]

Quick follow-up on the new concept direction from my earlier update — it's implemented now, I'm just wrapping documentation and testing.

The short version: the addon is pure source again. The prebuilt per-platform binaries in bin/ are gone; the MCP server now runs in-process on FreeCAD's bundled Python (stdlib only — no pip installs, no compiled artifacts). So the prebuilt-binary concern that prompted the rework no longer applies to what the Index serves.

One thing I'll flag for transparency: we've also written an optional connector for Claude Desktop (which only speaks stdio, so it needs a small stdio↔HTTP relay). It's a hand-rolled, zero-dependency Node script, and its source lives in the repo (mcp-stdio-shim/). For Claude Desktop it's packaged as an .mcpb bundle — that is a zip file, so that is a binary. That bundle is not included with the addon, and never travels through the Addon Manager; it's published as a GitHub Releases asset, it's a separate opt-in download documented in the readme for Claude Desktop users. So nothing compiled or zipped sits in the addon tree the Index serves.

No action needed — just keeping you in the loop, happy to adjust if you'd prefer a different arrangement.

[chennes]

I think the changes look good, and address all of my concerns. This Addon is appropriate as a global toolbar addon, so that does not pose an issue. If you plan to use release tags, please make a new one with these changes included, and I will add it to the index. If you'd prefer to use a release/development branch strategy instead, let me know what branch you'd like indexed.