freecad-mcp

MCP (Model Context Protocol) server for FreeCAD parametric 3D CAD modeling. Provides 165 tools across 15 modules for document management, primitives, booleans, sketching, part design, meshing, FEM, BIM, and more.

Prerequisites

• Node.js >= 18
• FreeCAD 0.21 or later installed

Installation

git clone https://github.com/sergiudanstan/freecad-mcp.git
cd freecad-mcp
npm install
npm run build

Setup

The server supports two modes: GUI mode (recommended) and headless mode (fallback).

GUI Mode (recommended)

GUI mode connects to a running FreeCAD instance so you can see changes live in the 3D viewport.

Step 1 — Start the FreeCAD socket server macro:

1. Open FreeCAD
2. Go to Macro > Macros…
3. Click “…” (browse) and navigate to the freecad_server.FCMacro file in this repo
4. Select it and click Execute
5. You should see in the FreeCAD console:

   MCP Socket Server listening on 127.0.0.1:12345
   MCP Server macro loaded. Waiting for connections...
   

The macro must be running before the MCP server connects. The server auto-detects the socket on startup.

Step 2 — Configure your MCP client:

Add the server to your MCP client configuration. For Claude Code, add to ~/.claude/settings.json:

{
  "mcpServers": {
    "freecad": {
      "command": "node",
      "args": ["/path/to/freecad-mcp/dist/index.js"]
    }
  }
}

Or via the CLI:

claude mcp add freecad node /path/to/freecad-mcp/dist/index.js

Headless Mode (fallback)

If FreeCAD GUI is not running, the server automatically falls back to headless mode using freecadcmd. This works for scripting and automation but you won’t see visual output.

The server looks for freecadcmd at /Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd by default. Override with:

{
  "mcpServers": {
    "freecad": {
      "command": "node",
      "args": ["/path/to/freecad-mcp/dist/index.js"],
      "env": {
        "FREECAD_CMD": "/your/path/to/freecadcmd"
      }
    }
  }
}

Tool Modules