Agent Link for FreeCAD

Not affiliated with or endorsed by the FreeCAD project or the FreeCAD project association (FPA); FreeCAD is the FPA's trademark. Get FreeCAD itself from freecad.org.

Agent Link lets an AI agent (Claude, or any client that speaks the Model Context Protocol) drive FreeCAD for you. You describe the part; the agent makes it, checks it, draws it and exports it, and you can watch every step in your own FreeCAD window. Every change is one FreeCAD undo step.

• What you need

• Install

• Connect your agent

• Where everything lives

• What the agent can do

• Platforms

• Token usage

• Troubleshooting

• Uninstall

• Credits and licence

For an agent setting this up: follow SETUP.md.

What you need

Check at any time with the setup check, which says what is missing and how to get it (it changes nothing):

uvx --from git+https://github.com/jamesK1000011/AgentLink-FreeCAD agentlink-freecad --check

or, from a copy of this folder, python3 agentlink_headless.py --check. In FreeCAD, Agent Link > Setup check does the same for the Claude extension.

The server itself runs in FreeCAD's own Python, so you never install FreeCAD's Python libraries by hand. Open FreeCAD once after installing it: that makes the user folder add-ons are installed into.

Related MCP server: freecad-tool-server

Install

Pick one.

1. The Claude Desktop extension (Mac)

Download freecad-agentlink.mcpb from the newest agentlink-v… release and double-click it; Claude Desktop installs it. It finds FreeCAD in Applications, installs Agent Link into FreeCAD and keeps it up to date. Its settings: the output folder (~/AgentLink by default), the FreeCAD app if it is not in Applications, and whether to keep the add-ons up to date.

2. FreeCAD's Addon Manager (custom repository)

1. In FreeCAD: Edit > Preferences > Addon Manager, under Custom repositories add https://github.com/jamesK1000011/AgentLink-FreeCAD, branch main.

2. Tools > Addon manager, find Agent Link, Install, restart FreeCAD.

3. Connect your agent (below).

3. By hand

Put this folder in FreeCAD's Mod folder as AgentLink. Find the folder with --check, or in FreeCAD's Python console with FreeCAD.getUserAppDataDir() (the Mod folder is inside it).

git clone https://github.com/jamesK1000011/AgentLink-FreeCAD "<FreeCAD user folder>/Mod/AgentLink"

Restart FreeCAD. To use it headless only (no window), you need no install at all: the uvx command in Connect your agent runs it.

Connect your agent

Copy-paste configs for each client are in docs/clients/: Claude Desktop, Claude Code, Cursor, VS Code, LM Studio, OpenCode with Ollama and any other MCP client. ChatGPT needs a remote server and is out of scope (why).

They all start the same command:

uvx --from git+https://github.com/jamesK1000011/AgentLink-FreeCAD agentlink-freecad

It finds FreeCAD, serves in FreeCAD's own Python, and writes files to ~/AgentLink (--out DIR for another folder).

To watch the agent work, open FreeCAD, pick the Agent Link workbench and press Start link. Calls then arrive in the document open in your window; with the link off they run headless. The link listens on 127.0.0.1 only and pairs with the server before it takes a call.

Where everything lives

• The workbench: pick Agent Link from FreeCAD's workbench list.

• The toolbar: Start link, Stop link, Agent Link panel, and Screenshot for the agent (Alt+Shift+S: take the window, mark it up, leave it for the agent).

• The Agent Link menu: the same, plus Setup check and Updates (which Agent Link this is and how it is kept up to date).

• The panel, docked beside the model tree, in tabs:

  • Notes: notes pinned to the parts, between you and the agent; the agent's questions to you;

  • Steps: the build played back step by step, a picture a step;

  • Review: the part's review, from a reviewer add-on when one is installed;

  • Activity: each thing the agent does in this window, as it happens;

  • the tabs of installed add-ons, in their own places between these;

  • the usage strip along the bottom (Token usage).

• The files: exports, drawings and pictures go to ~/AgentLink (or the folder you chose).

Agent Link is a hub. Add-ons installed beside it bring their own tools, guides and panel tabs; Agent Link finds them when FreeCAD starts and names none of them in its code. Add-ons such as Workshop for FreeCAD (standard parts, printing and cutting, electronics, documents), ScanRuler for FreeCAD (scans and reverse engineering), Agent Link for OrcaSlicer, SafetyNet (checkpoints and recovery) and Texturizer each keep their own repository and licence.

What the agent can do

Agent Link itself declares 392 tools in 29 groups; a FreeCAD build without a workbench (FEM, CAM …) serves fewer, and each installed add-on adds its own groups. Groups marked lean are listed from the start; the agent turns on the rest with tool_groups.

Each group has a guide the agent reads (guide_read). Any tool runs by name whether it is listed or not. AGENTLINK_TOOLS=full lists every tool from the start; leave it unset for small local models (see docs/clients/).

The table is generated: python3 scripts/tool_summary.py rewrites it, and --check (run by the tests) fails when it is stale.

Platforms

Windows reports are welcome: open an issue saying what worked and what did not.

Token usage

The panel's usage strip shows what the agent's calls cost in tokens: the tool list, each call and its answer, and pictures. These are estimates from the text and image sizes, not your provider's billing. The tool list starts lean, and add-ons that aren't installed cost nothing: their tools are never listed. usage_report gives the agent the same figures; they are kept in ~/AgentLink/usage. AGENTLINK_USAGE=off turns the meter off.

Troubleshooting

Run the setup check first (agentlink-freecad --check); it names what is missing and how to get it.

Logs.

• Claude Desktop: ~/Library/Logs/Claude/mcp-server-*.log (Mac), %APPDATA%\Claude\logs\mcp-server-*.log (Windows).

• The Claude extension's launcher (Mac): ~/Library/Logs/FreeCAD Agent Link/launcher.log.

• Other clients show the server's messages (its stderr) in their own MCP log or output panel.

• In FreeCAD: View > Panels > Report view.

"Server disconnected". The client started the server and it stopped. Read the log above: the last lines say why. Most often FreeCAD was not found (install it, or set FREECAD_APP to the app or FREECAD_LIB to its lib folder), uvx was not on the client's PATH (give its full path, e.g. ~/.local/bin/uvx), or FreeCAD is older than 1.1. Restart the client after a fix.

"Open FreeCAD once". A FreeCAD that has never been opened has no user folder, so nothing can be installed into it. Open FreeCAD, close it, and try again.

The window shows nothing. Pick the Agent Link workbench and press Start link; calls go headless while the link is off.

The Claude extension cannot load (Mac): Agent Link > Setup check in FreeCAD reports the launcher and offers Mend when it can fix it.

Uninstall

• Claude Desktop extension: Settings > Extensions > Agent Link for FreeCAD > Uninstall. Then remove the add-on as below.

• Addon Manager: Tools > Addon manager > Agent Link > Uninstall.

• By hand: delete <FreeCAD user folder>/Mod/AgentLink.

• The client config: remove the agentlink-freecad entry from your client's MCP settings. uv cache clean agentlink-freecad drops uv's copy.

• Your files: ~/AgentLink (exports, pictures, usage) and ~/.config/freecad-agentlink (the launcher, add-ons fetched by app_extensions) are yours to keep or delete.

Tests

python3 -m unittest discover -s tests runs the protocol, data, packaging and release tests anywhere; the tool tests need FreeCAD and are skipped without it. CI (.github/workflows/ci.yml) runs them all on Linux with FreeCAD 1.0 and the newest release, with PrusaSlicer and OrcaSlicer.

Credits and licence

• The way Agent Link works, one call per job, small answers in millimetres and grams, and refusals that say what to do instead, follows ScanRuler by Stefan Hermann (CNC Kitchen). The panel's notes and step playback are inspired by it. Agent Link copies none of ScanRuler's code.

• FreeCAD and the libraries and programs it brings (OpenCASCADE, CalculiX, Gmsh, Netgen) do the modelling and the analysis.

• Icons are adapted from Tabler Icons (MIT, tabler.io) and Pictogrammers Material Design Icons (Apache-2.0, pictogrammers.com); FreeCAD's own icons are used by name. See agentlink/icons/CREDITS.md.

The code is LGPL-2.1-or-later (LICENSE), so it can sit beside FreeCAD's own code, and uses only FreeCAD's public Python API. The data files (agentlink/data/) are CC BY 4.0 (LICENSE-DATA). Every file's licence is stated in its SPDX header or in REUSE.toml; the licence texts are in LICENSES/.

FreeCAD's AI_POLICY.md does not accept AI-generated pull requests, so Agent Link is a separate add-on, not an upstream change.