Skip to content

Quick Start

Install the server and FreeCAD workbench, pair them once, and connect your AI assistant. No source checkout or developer tools are required.

Compatibility: Install both the server and workbench at version 0.7.0 or later. Older 0.6.x releases do not support bridge pairing.

What you need

  • FreeCAD 1.1.4 or newer is recommended for security.
  • An MCP-compatible assistant, such as Codex or Claude Desktop.
  • Internet access to install the server and download the workbench.

The MCP server runs on the same computer and user account as FreeCAD. Install and run software only from sources you trust: the bridge lets your assistant execute Python with your FreeCAD user's permissions.

1. Install the MCP server

Choose one server installation method:

  • Stable package: use the uv command below, or install with pip.
  • GitHub release, including RC testing: download the server wheel and follow the release asset steps. The instructions include a stable 0.7.0 example for macOS, Linux, and Windows.

For the stable uv method, install uv for your operating system, then open a new Terminal (macOS/Linux) or PowerShell (Windows) and run:

uv tool install freecad-robust-mcp
uv tool update-shell

Open a new terminal and check that the command is available:

freecad-mcp --version

If your shell cannot find it, see uv's executable directory instructions. For a downloaded server wheel, including a release candidate, see the GitHub release asset installation steps.

2. Install the FreeCAD workbench

  1. If you need to find the active profile, follow the Python console step below while that version of FreeCAD is open. Then quit FreeCAD.
  2. Open the workbench releases, select a Robust MCP Bridge workbench release compatible with your server, and download its freecad-mcp-workbench ZIP file. For stable installations, choose a stable release; for RC testing, choose the matching pre-release version. For example, server 0.7.0 pairs with workbench 0.7.0.
  3. Extract the ZIP. Open the FreeCAD profile's Mod folder, and move the extracted workbench folder into it. The folder you move must directly contain package.xml and the freecad folder. If Mod does not exist, create it. For 0.7.0, move the entire freecad-mcp-workbench-0.7.0 folder, not the inner freecad or RobustMCPBridge folder. The resulting structure is:
Mod/
└── freecad-mcp-workbench-0.7.0/
    ├── package.xml
    ├── LICENSE-CODE
    ├── LICENSE-MIT
    ├── LICENSE-ICON
    ├── NOTICE
    └── freecad/
        └── RobustMCPBridge/
            ├── __init__.py
            ├── init_gui.py
            └── freecad_mcp_bridge/

For other releases, the top-level folder contains that release's version. Check that extraction did not add a second folder of the same name between Mod and package.xml.

Operating system Typical profile folder
macOS ~/Library/Application Support/FreeCAD/v1-1/Mod/
Windows %APPDATA%\FreeCAD\v1-1\Mod\
Linux ~/.local/share/FreeCAD/v1-1/Mod/

These examples are for FreeCAD 1.1. Use the profile for the version you actually start; for example, a development build may use v27-1/Mod. Custom and older profiles can use different locations. To find the active profile, open View > Panels > Python console in that FreeCAD version and enter import os; print(os.path.join(App.getUserAppDataDir(), "Mod")). In Finder, use Go > Go to Folder to open the macOS path; on Windows, paste the path into File Explorer's address bar. 4. If another Robust MCP Bridge installation is already in that profile, move the old folder out of Mod so FreeCAD does not load two copies. Restart FreeCAD after installing.

The workbench is not currently listed in the public FreeCAD Addon Manager. The .tar.gz workbench asset contains the same package as the ZIP. You do not need cam-gate-v1.json, which is used by release CI.

When updating, update both components: install the new server version and replace the workbench archive in every FreeCAD profile you use. Quit FreeCAD first, then restart it and reconnect your assistant. Keep your existing pairing unless you intend to replace it. See the release asset update steps.

3. Pair and start the bridge

If you already paired this user account, keep the existing credential and skip this command. Otherwise, in a terminal on the same computer and user account that runs FreeCAD, run:

freecad-mcp --pair-bridge

Open FreeCAD, select Robust MCP Bridge from the workbench selector, and click Start MCP Bridge. If it is already running, leave it running. Pairing is shared by compatible workbench installations under your user account; you do not need to copy a credential into each FreeCAD profile.

If freecad-mcp is not found, run it by its full path using one of these commands instead:

# macOS or Linux
"$(uv tool dir --bin)/freecad-mcp" --pair-bridge

# Windows PowerShell
& (Join-Path (uv tool dir --bin) 'freecad-mcp.exe') --pair-bridge

The bridge cannot start until pairing is complete. See pairing and security settings for troubleshooting.

4. Connect your assistant

Configure your assistant to launch freecad-mcp over stdio. If the app cannot find the command, specify the full executable path: uv tool dir --bin shows its directory. On Windows the executable is freecad-mcp.exe. Restart or reconnect the assistant after changing its settings.

Choose your assistant below. Replace /absolute/path/to/freecad-mcp with the actual executable path; quote paths containing spaces. On Windows, use the path to freecad-mcp.exe.

Codex Desktop or Codex CLI

Both use ~/.codex/config.toml. Add the following entry, keeping any other servers already in the file:

[mcp_servers.freecad]
command = "/absolute/path/to/freecad-mcp"

On Windows, use forward slashes or escaped backslashes in the TOML string. Alternatively, the Codex CLI can add the same entry:

codex mcp add freecad -- "/absolute/path/to/freecad-mcp"

Start a new Codex session after updating the configuration.

Claude Desktop

Edit claude_desktop_config.json in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows. Add the freecad entry under mcpServers, preserving existing entries:

{
  "mcpServers": {
    "freecad": {
      "command": "/absolute/path/to/freecad-mcp"
    }
  }
}

On Windows, use forward slashes or double each backslash in the JSON path. Fully quit and reopen Claude Desktop after editing the file.

Claude Code CLI

Run this command to make the server available across your projects:

claude mcp add --transport stdio --scope user freecad -- "/absolute/path/to/freecad-mcp"

In a Claude Code session, use /mcp to check the connection.

Other agents have similar MCP settings: add a local stdio server with the same executable path, following that agent's instructions. See the client configuration guide for more details. The default connection uses local XML-RPC, so no environment variables or HTTP API key are needed for this setup. Start FreeCAD and the bridge before asking your assistant to use the tools.

5. Verify the connection

Ask your assistant:

Check the FreeCAD connection and tell me the FreeCAD version.

If it cannot connect, verify the bridge is running, that the assistant is using the installed executable, and that FreeCAD and the assistant run as the same user. See Installation for additional checks.

Try your first model

Try these example prompts with your AI assistant:

Simple Box

"Create a new FreeCAD document and add a box that is 20mm x 10mm x 5mm"

Parametric Part with Fillet

"Create a parametric bracket:
1. Start with a 50x30mm rectangular sketch
2. Extrude it 10mm
3. Add a 3mm fillet to all edges"

Export for 3D Printing

"Export the current model to STL format for 3D printing"

Explore available tools

The MCP server provides 150+ tools organized into categories:

Category Examples
Primitives create_box, create_cylinder, create_sphere
PartDesign create_sketch, pad_sketch, pocket_sketch
Operations boolean_operation, fillet_edges, chamfer_edges
Export export_stl, export_step, export_3mf
View (GUI) get_screenshot, set_object_color

See the Tools Reference for the complete list.

Example Workflows

Create a Mounting Bracket

"Help me create a mounting bracket with:
- 60x40mm base plate, 5mm thick
- Two mounting holes (5mm diameter) at the corners
- A vertical wall 30mm tall on one edge
- 2mm fillets on all external edges"

Modify an Existing Model

"Open my_part.FCStd and:
1. List all the objects in the document
2. Change the height of the Pad feature from 10mm to 15mm
3. Save the document"

Debug a Macro

"Read the macro 'MyMacro' and explain what it does.
Then run it and show me any errors."

Tips for Effective AI-Assisted Modeling

  1. Be specific about dimensions - Include units (mm, cm, inches) in your requests
  2. Use parametric approaches - Ask for PartDesign workflows instead of direct Part operations for parts you'll modify
  3. Check console output - If something goes wrong, ask the AI to check the FreeCAD console for errors
  4. Take screenshots - In GUI mode, ask for screenshots to verify the model looks correct
  5. Save frequently - Ask the AI to save your document after significant changes

Next Steps