# Configuration - FreeCAD Robust MCP Suite
FreeCAD Robust MCP Suite - MCP Server, Bridge Workbench, and Macros for AI assistant integration

Skip to content

# Configuration

Configure the FreeCAD Robust 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 Robust 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/Windows)

### 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)

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 Robust 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 Robust 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/FreecadRobustMCPBridge/freecad_mcp_bridge/blocking_bridge.py

## Next Steps

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

2026-01-12
2026-01-06