Configuration¶

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

The server reads settings from its process environment. It does not automatically load a .env file from the current working directory. Configure variables in your MCP client or explicitly load them into the environment before startup.

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`	Default execution timeout in ms (1000-600000)	`30000`

Data and network connections¶

The workbench does not start a bridge listener by default. After you start it, its JSON-RPC and XML-RPC listeners bind to the local machine (by default ports 9876 and 9875); the separately installed MCP server connects to the bridge using the paired credential. The workbench does not itself transmit model data to an external AI provider. An MCP client you configure can request document contents, screenshots, or other results and may send them to its own provider according to that client's settings and privacy policy. Review those settings before sharing sensitive models.

If a bridge port is already in use, the Report view identifies the affected transport and the bridge keeps the other transport available when possible. Stop the application using the port, or choose a different port under FreeCAD Preferences → Robust MCP Bridge → Network Ports and restart the bridge. Set the matching FREECAD_XMLRPC_PORT or FREECAD_SOCKET_PORT in your MCP client configuration. XML-RPC is the default connection mode; an unavailable XML-RPC listener will prevent that default connection even if JSON-RPC works. The bridge remains restricted to loopback and paired clients.

The optional auto-start preferences make the bridge start in future FreeCAD sessions. The optional MCP HTTP transport is separate from the FreeCAD bridge; if configured for remote access, requests and their results can leave the machine. The bridge pairing credential is stored locally as described below; the workbench also saves its settings in FreeCAD preferences. When this data handling changes, release notes and this documentation should describe the change before users opt in.

Pairing the FreeCAD bridge¶

For XML-RPC and socket modes, create a pairing once under the same user account that runs FreeCAD and the MCP server:

freecad-mcp --pair-bridge

Then start or restart the FreeCAD bridge and configure the harness to launch the MCP server as usual. Both processes load the pairing automatically; the secret does not need to appear in the harness configuration. The command refuses to replace an existing pairing. If either process cannot load valid credentials, the bridge connection fails rather than falling back to unauthenticated access.

On macOS and Linux, the credential is stored in ~/.freecad-robust-mcp/bridge-credential.json inside a user-owned private directory. On Windows, the implementation uses a locally persisted generic credential named FreeCADRobustMCPBridge:default in Windows Credential Manager. Cross-platform CI exercises Windows pairing and the Windows credential store. Both processes must run as the same user and see the same credential store; a container or different user account needs separate credential provisioning.

Pairing blocks clients without the credential. It does not isolate FreeCAD from malicious software already running as the same user, which may read or use the credential or modify the workbench. The bridge can execute Python with the FreeCAD user's privileges. Back up the credential only in a secure location.

To replace a compromised pairing, stop the bridge and MCP server, remove the existing credential from its store, run freecad-mcp --pair-bridge, and restart both processes. All clients using the previous credential will stop working.

HTTP authentication¶

The default stdio transport does not use an HTTP API key. When using FREECAD_TRANSPORT=http, generate a key with freecad-mcp --generate-http-api-key, store it securely, and supply it to the server in FREECAD_HTTP_API_KEY. HTTP startup fails if the key is missing or malformed. Configure the harness to send Authorization: Bearer <key> on every request. The key must be at least 32 visible ASCII characters; the generation command produces a random key.

The default HTTP bind is loopback. For remote access, use HTTPS with a trusted TLS-terminating proxy and protect the key in transit and at rest. A static key does not implement MCP OAuth discovery or automatic credential enrollment. Rotate it by generating a new key, updating server and client configuration, and restarting the server.

Arbitrary Code Tools¶

The FREECAD_ALLOW_UNSAFE_CODE setting defaults to false. The server does not expose execute_python, safe_execute, run_macro, create_macro, or create_macro_from_template by default. Set FREECAD_ALLOW_UNSAFE_CODE=true in the MCP server environment before startup to expose them. Restart the server after changing this setting.

This setting controls the MCP tool list; it is not a sandbox or a bridge authorization mechanism. Other CAD tools still generate Python for FreeCAD, and an authenticated bridge client can submit code directly. Use it together with bridge authentication and a trusted client.

While the GUI bridge is running, its status display warns that authorized clients can execute Python. This warning reflects the bridge's capabilities, including code generated by ordinary CAD tools; it is shown regardless of the MCP server's arbitrary-code tool setting.

The workbench limits a returned value to a 1,000,000-byte structural budget and portable XML-RPC/JSON values. A result exceeding that budget, including a large screenshot, returns ResultValidationError rather than partial data. The operation may already have modified the document when this error is reported. Captured stdout and stderr are independently limited and marked when truncated. Characters that XML cannot represent, such as a null byte, are rendered as visible escape sequences in captured output.

Execution Timeouts¶

Execution timeout selection is consistent across xmlrpc, socket, and embedded modes:

An execute_python(timeout_ms=...) value overrides all other settings.
Otherwise, FREECAD_TIMEOUT_MS supplies the server-wide default.
If neither is set, the default is 30000 milliseconds.

Both configured and per-call values must be between 1000 and 600000 milliseconds. XML-RPC sends the effective timeout to the FreeCAD workbench; one-argument XML-RPC clients remain supported with the 30000 millisecond workbench default.

When connected to an older Robust MCP Bridge workbench that accepts only execute(code), the MCP server retries only the specific XML-RPC arity fault from that workbench. This preserves execution compatibility, but the older workbench still uses its 30000 millisecond timeout. Upgrade the workbench to use configured or per-call timeouts longer than 30 seconds.

Warning: A timeout is not process cancellation. The bridge cancels a request that is still waiting in its queue. Python code that has already started inside FreeCAD cannot be interrupted safely and may continue after the caller receives a timeout. Do not automatically retry a timed-out state-changing operation. Inspect the document state first, or make the operation idempotent.

Socket requests that expire while waiting for the request lock or reconnecting before any write attempt return RequestNotSentError and explicitly confirm that the code was not executed. If a write was attempted, the result remains a general TimeoutError because FreeCAD may have started the operation.

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¶

Codex Desktop and CLI¶

Both use ~/.codex/config.toml. Add an entry with the full path to the installed executable, keeping any other servers already in the file:

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

Alternatively, run codex mcp add freecad -- "/absolute/path/to/freecad-mcp". Start a new Codex session after changing the configuration. On Windows, use freecad-mcp.exe and forward slashes or escaped backslashes in TOML.

Claude Desktop¶

Add the entry below to claude_desktop_config.json: on macOS, the file is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows, it is %APPDATA%\Claude\claude_desktop_config.json. Keep any existing entries and use the full path to the installed executable. Find its directory with uv tool dir --bin. Restart Claude Desktop after editing the file.

{
  "mcpServers": {
    "freecad": {
      "command": "/absolute/path/to/freecad-mcp",
      "env": {
        "FREECAD_MODE": "xmlrpc"
      }
    }
  }
}

On Windows use the path to freecad-mcp.exe, with backslashes escaped as \\ in JSON.

Claude Code CLI¶

Add the server for your user account, replacing the example path with the installed executable:

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

Run /mcp inside Claude Code to check the connection. See the Claude Code MCP guide for project-scoped configuration and additional options.

Other MCP clients¶

Other agents generally support the same setup: register the installed freecad-mcp executable as a local stdio MCP server, then reconnect the agent. The settings and file location depend on the agent.

If installed from source with mise/uv:

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

Docker Desktop Configuration¶

Docker Desktop forwards host.docker.internal to services listening on the host loopback interface. The RC4 image example below configures networking only: the container must also receive the existing bridge pairing credential. Pairing on the host does not automatically provision the container, and a portable secure provisioning procedure has not yet been validated. Run the MCP server on the host until the container's credential has been provisioned securely.

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

Do not expose the FreeCAD bridge

The bridge requires pairing before accepting Python execution inside FreeCAD and must remain loopback-only. Do not rebind ports 9875 or 9876 to 0.0.0.0 or a LAN address.

Linux Docker Engine¶

The container-to-host setup is not currently supported with Docker Engine on Linux. host-gateway resolves to the host's container-bridge address, but the FreeCAD bridge listens on loopback. Consequently, adding host.docker.internal:host-gateway does not make the bridge reachable.

Run freecad-mcp directly on the Linux host when connecting to a FreeCAD GUI session. FREECAD_SOCKET_HOST selects the address that the MCP server dials; it does not change the bridge's listening address. Protected remote transport is required before non-loopback listening can be supported safely.

AI Guidance Auto-Loading (Recommended)¶

The FreeCAD MCP server provides built-in guidance resources and prompts to help AI assistants work effectively with FreeCAD. For the best experience, configure your AI client to automatically load this guidance when connecting.

Available Guidance¶

Name	Type	Description
`freecad-startup`	Prompt	Essential startup checklist and quick reference (recommended for auto-load)
`freecad://best-practices`	Resource	Comprehensive guidance on patterns, pitfalls, and workflows
`freecad-guidance`	Prompt	Task-specific guidance (partdesign, sketching, boolean, etc.)

Claude Desktop / Claude Code Configuration¶

Add the customInstructions field to auto-load guidance on connection:

{
  "mcpServers": {
    "freecad": {
      "command": "freecad-mcp",
      "env": {
        "FREECAD_MODE": "xmlrpc"
      },
      "customInstructions": "When connecting to FreeCAD, first invoke the 'freecad-startup' prompt to get essential guidance. For complex tasks, also read the 'freecad://best-practices' resource."
    }
  }
}

Alternative: System Prompt Addition¶

If your MCP client doesn't support customInstructions, add this to your system prompt or initial message:

Before working with FreeCAD:
1. Invoke the 'freecad-startup' prompt for essential guidance
2. For complex tasks, read the 'freecad://best-practices' resource
3. For specific tasks, use 'freecad-guidance' prompt with task_type parameter

Manual Invocation¶

If auto-loading isn't configured, you can always ask the AI to:

"Run the freecad-startup prompt"
"Read the freecad://best-practices resource"
"Get guidance for PartDesign" (uses freecad-guidance with task_type="partdesign")

What the Guidance Provides¶

freecad-startup prompt:

Session initialization checklist
Critical rules for parametric parts
Error prevention patterns
Quick reference table for common tasks
GUI vs headless mode considerations

freecad://best-practices resource:

Version compatibility notes (FreeCAD 1.x API changes)
Validation-first workflow patterns
Common pitfalls and solutions
Recommended workflows for different tasks
Error recovery strategies

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
# Use FreeCADCmd instead if that is the executable installed on your system.
freecadcmd ~/.local/share/FreeCAD/v1-1/Mod/RobustMCPBridge/freecad/RobustMCPBridge/freecad_mcp_bridge/blocking_bridge.py

The direct path is a FreeCAD 1.1 source-installation example. Use the active profile’s Mod directory and the actual package directory; run App.getUserAppDataDir() in FreeCAD’s Python console to find its user data directory.

Next Steps¶

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