Files

T

Sean P. KaneandGitHub 6a6cad9e65 feat: Add workbench and major cleanup, refactor, and updates (#21 )

* FreeCAD addon support for Workbench and Plugins

* docs: refactor docs and clean up linters, etc.

* Remove mdformat

* test: improve test coverage

* test:Lots of general fixes

* chore: more general fixes

2026-01-06 15:44:27 -08:00

4.5 KiB

Raw Blame History

Configuration

Configure the FreeCAD MCP Server using environment variables and MCP client settings.

Environment Variables

Variable	Description	Default
`FREECAD_MODE`	Connection mode: `xmlrpc`, `socket`, or `embedded`	`xmlrpc`
`FREECAD_PATH`	Path to FreeCAD's lib directory (embedded mode only)	Auto-detect
`FREECAD_SOCKET_HOST`	Socket/XML-RPC server hostname	`localhost`
`FREECAD_SOCKET_PORT`	JSON-RPC socket server port	`9876`
`FREECAD_XMLRPC_PORT`	XML-RPC server port	`9875`
`FREECAD_TIMEOUT_MS`	Execution timeout in ms	`30000`

Connection Modes

The MCP server supports three connection modes:

Mode	Description	Platform Support
`xmlrpc`	Connects to FreeCAD via XML-RPC (port 9875)	All platforms (recommended)
`socket`	Connects via JSON-RPC socket (port 9876)	All platforms
`embedded`	Imports FreeCAD directly into process	Linux only (crashes on macOS)

XML-RPC Mode (Recommended)

The default and recommended mode. Works on all platforms.

export FREECAD_MODE=xmlrpc
freecad-mcp

Socket Mode

Alternative to XML-RPC using JSON-RPC over TCP sockets.

export FREECAD_MODE=socket
freecad-mcp

Embedded Mode (Linux Only)

!!! warning "Linux Only" Embedded mode only works on Linux. On macOS and Windows, it will crash because FreeCAD's FreeCAD.so library links to its bundled Python, which conflicts with external Python interpreters.

Embedded mode imports FreeCAD directly into the MCP server process for fastest execution.

export FREECAD_MODE=embedded
export FREECAD_PATH=/usr/lib/freecad/lib
freecad-mcp

Note: Embedded mode testing is minimal. For production use, prefer xmlrpc or socket modes.

MCP Client Configuration

Claude Code / Claude Desktop

Add to ~/.claude/claude_desktop_config.json or a project .mcp.json file:

{
  "mcpServers": {
    "freecad": {
      "command": "freecad-mcp",
      "env": {
        "FREECAD_MODE": "xmlrpc"
      }
    }
  }
}

If installed from source with mise/uv:

{
  "mcpServers": {
    "freecad": {
      "command": "/path/to/mise/shims/uv",
      "args": ["run", "--project", "/path/to/freecad-robust-mcp-and-more", "freecad-mcp"],
      "env": {
        "FREECAD_MODE": "xmlrpc"
      }
    }
  }
}

Docker Configuration

{
  "mcpServers": {
    "freecad": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "FREECAD_MODE=xmlrpc",
        "-e", "FREECAD_SOCKET_HOST=host.docker.internal",
        "spkane/freecad-robust-mcp"
      ]
    }
  }
}

GUI vs Headless Mode

FreeCAD can run in two modes, and the MCP server works with both:

Feature	Headless Mode	GUI Mode
Object creation	Yes	Yes
Boolean operations	Yes	Yes
Export (STEP, STL, etc.)	Yes	Yes
Save documents	Yes	Yes
Screenshots	No	Yes
Object colors	No	Yes
Object visibility	No	Yes
Camera control	No	Yes
Interactive selection	No	Yes

Starting FreeCAD

GUI Mode (for interactive work with visual feedback):

# Using just commands (from source)
just freecad::run-gui

# Or start FreeCAD normally and click "Start Bridge" in the workbench

Headless Mode (for automation, CI/CD, or when you don't need visual feedback):

# Using just commands (from source)
just freecad::run-headless

# Or run directly with FreeCADCmd
FreeCADCmd ~/.local/share/FreeCAD/Mod/FreecadRobustMCP/freecad_mcp_bridge/headless_server.py

Next Steps

Quick Start - Create your first model with AI assistance
Connection Modes - Detailed guide on different connection modes

4.5 KiB Raw Blame History