Skip to content
Back to search

freecad-addon-robust-mcp-server

The FreeCAD Robust MCP server and MCP Bridge Workbench/Addon

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/spkane/freecad-addon-robust-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/spkane/freecad-addon-robust-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/spkane--freecad-addon-robust-mcp-server/badge.svg)](/listings/spkane--freecad-addon-robust-mcp-server)

HTML

<a href="/listings/spkane--freecad-addon-robust-mcp-server"><img src="/api/listings/spkane--freecad-addon-robust-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Using pip (recommended)

pip install freecad-robust-mcp

Using mise and just (from source)

git clone https://github.com/spkane/freecad-addon-robust-mcp-server.git
cd freecad-addon-robust-mcp-server

# Install mise via the Official mise installer script (if not already installed)
curl https://mise.run | sh

mise trust
mise install
just setup

Using Docker

Run the Robust MCP Server in a container. This is useful for isolated environments or when you don't want to install Python dependencies on your host.

# Pull from Docker Hub (when published)
docker pull spkane/freecad-robust-mcp

# Or build locally
git clone https://github.com/spkane/freecad-addon-robust-mcp-server.git
cd freecad-addon-robust-mcp-server
docker build -t freecad-robust-mcp .

# Or use just commands (if you have mise/just installed)
just docker::build        # Build for local architecture
just docker::build-multi  # Build multi-arch (amd64 + arm64)

**Note:** The containerized Robust MCP Server only supports `xmlrpc` and `socket` modes since FreeCAD runs on your host machine (not in the container). The container connects to FreeCAD via `host.docker.internal`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 805 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # FreeCAD Robust MCP Server
  2. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
  3. [![PyPI Version](https://img.shields.io/pypi/v/freecad-robust-mcp)](https://pypi.org/project/freecad-robust-mcp/)
  4. [![Python Versions](https://img.shields.io/pypi/pyversions/freecad-robust-mcp)](https://pypi.org/project/freecad-robust-mcp/)
  5. [![Docker Image Version](https://img.shields.io/docker/v/spkane/freecad-robust-mcp?sort=semver&label=docker)](https://hub.docker.com/r/spkane/freecad-robust-mcp)
  6. [![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://spkane.github.io/freecad-addon-robust-mcp-server/)
  7. [![CI Tests](https://github.com/spkane/freecad-addon-robust-mcp-server/actions/workflows/test.yaml/badge.svg)](https://github.com/spkane/freecad-addon-robust-mcp-server/actions/workflows/test.yaml)
  8. [![Docker Build](https://github.com/spkane/freecad-addon-robust-mcp-server/actions/workflows/docker.yaml/badge.svg)](https://github.com/spkane/freecad-addon-robust-mcp-server/actions/workflows/docker.yaml)
  9. [![Pre-commit](https://github.com/spkane/freecad-addon-robust-mcp-server/actions/workflows/pre-commit.yaml/badge.svg)](https://github.com/spkane/freecad-addon-robust-mcp-server/actions/workflows/pre-commit.yaml)
  10. [![CodeQL](https://github.com/spkane/freecad-addon-robust-mcp-server/actions/workflows/codeql.yaml/badge.svg)](https://github.com/spkane/freecad-addon-robust-mcp-server/actions/workflows/codeql.yaml)
  11. An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that enables integration between AI assistants (Claude, GPT, and other MCP-compatible tools) and [FreeCAD](https://www.freecadweb.org/), allowing AI-assisted development and debugging of 3D models, macros, and workbenches.
  12. ## Table of Contents
  13. <!--TOC-->
  14. - [FreeCAD Robust MCP Server](#freecad-robust-mcp-server)
  15. - [Table of Contents](#table-of-contents)
  16. - [Features](#features)
  17. - [Security](#security)
  18. - [Installation Requirements / Dependencies](#installation-requirements--dependencies)
  19. - [For Users](#for-users)
  20. - [Quick Links](#quick-links)
  21. - [Robust MCP Server](#robust-mcp-server)
  22. - [Installation](#installation)
  23. - [Using pip](#using-pip)
  24. - [Using GitHub release assets](#using-github-release-assets)
  25. - [Using uv (from source)](#using-uv-from-source)
  26. - [Using Docker](#using-docker)
  27. - [Configuration](#configuration)
  28. - [Environment Variables](#environment-variables)
  29. - [Connection Modes](#connection-modes)
  30. - [MCP Client Configuration](#mcp-client-configuration)
  31. - [Usage](#usage)
  32. - [Starting the MCP Bridge in FreeCAD](#starting-the-mcp-bridge-in-freecad)
  33. - [Option A: Using the Workbench (Recommended)](#option-a-using-the-workbench-recommended)
  34. - [Option B: Using just commands (from source)](#option-b-using-just-commands-from-source)
  35. - [Uninstalling the MCP Bridge](#uninstalling-the-mcp-bridge)
  36. - [Checking for Legacy Components](#checking-for-legacy-components)
  37. - [Manual Cleanup (if needed)](#manual-cleanup-if-needed)
  38. - [Running Modes](#running-modes)
  39. - [XML-RPC Mode](#xml-rpc-mode)
  40. - [Socket Mode (Recommended)](#socket-mode-recommended)
  41. - [Headless Mode](#headless-mode)
  42. - [Embedded Mode (Linux Only)](#embedded-mode-linux-only)
  43. - [Available Tools](#available-tools)
  44. - [Execution & Debugging (5 tools)](#execution--debugging-5-tools)
  45. - [Document Management (7 tools)](#document-management-7-tools)
  46. - [Object Creation - Primitives (8 tools)](#object-creation---primitives-8-tools)
  47. - [Object Management (12 tools)](#object-management-12-tools)
  48. - [PartDesign - Sketching (14 tools)](#partdesign---sketching-14-tools)
  49. - [PartDesign - Patterns & Edges (5 tools)](#partdesign---patterns--edges-5-tools)
  50. - [View & Display (11 tools)](#view--display-11-tools)
  51. - [Undo/Redo (3 tools)](#undoredo-3-tools)
  52. - [Export/Import (7 tools)](#exportimport-7-tools)
  53. - [Macro Management (6 tools)](#macro-management-6-tools)
  54. - [Parts Library (2 tools)](#parts-library-2-tools)
  55. - [For Developers](#for-developers)
  56. - [Robust MCP Server Development](#robust-mcp-server-development)
  57. - [Prerequisites](#prerequisites)
  58. - [Initial Setup](#initial-setup)
  59. - [MCP Client Configuration (Development)](#mcp-client-configuration-development)
  60. - [Development Workflow](#development-workflow)
  61. - [Running FreeCAD with the MCP Bridge](#running-freecad-with-the-mcp-bridge)
  62. - [GUI Mode (recommended for development)](#gui-mode-recommended-for-development)
  63. - [Headless Mode (for automation/CI)](#headless-mode-for-automationci)
  64. - [Running Tests](#running-tests)
  65. - [Code Quality](#code-quality)
  66. - [Architecture](#architecture)
  67. - [Acknowledgements](#acknowledgements)
  68. - [Related Projects](#related-projects)
  69. - [License](#license)
  70. <!--TOC-->
  71. > The macros that were originally in this repo under the `/macros` directory have been permanently moved to two new GitHub repos:
  72. >
  73. > - [spkane/freecad-macro-cut-for-magnets](https://github.com/spkane/freecad-macro-cut-for-magnets)
  74. > - [spkane/freecad-macro-3d-print-multi-export](https://github.com/spkane/freecad-macro-3d-print-multi-export)
  75. **FreeCAD Forum:** [addon discussion post](https://forum.freecad.org/viewtopic.php?p=866012)
  76. ## Features
  77. - **150+ MCP Tools**: Comprehensive CAD operations including primitives, PartDesign, booleans, export
  78. - **Multiple Connection Modes**: JSON-RPC socket (recommended), XML-RPC, or embedded
  79. - **GUI & Headless Support**: Full modeling in headless mode, plus screenshots/colors in GUI mode
  80. - **Macro Development**: Create, inspect, and template FreeCAD macros via MCP
  81. ## Security
  82. The bridge accepts Python from paired clients and runs it with the FreeCAD
  83. user's permissions, including access to files and the network. When a GUI
  84. bridge is running, workbench 0.8.0 and later show a persistent, non-modal
  85. status warning. The workbench indicator's tooltip includes listener details.
  86. Stop the bridge when it is not needed.
  87. In workbench 0.7.0 and later, bridge listeners are restricted to loopback and
  88. require pairing. Older 0.6.x bridges do not provide pairing authentication.
  89. Pairing does
  90. not prevent a trusted client from following malicious instructions in a model
  91. or protect against malicious software running as the same user. The MCP server
  92. does not expose arbitrary Python and macro execution tools by default, but
  93. ordinary modeling tools still execute Python through the bridge. Client tool
  94. approval behavior varies. Starting with version 0.8.0, the optional
  95. `execute_python` and `safe_execute` tools require a local FreeCAD approval
  96. dialog by default on a supported GUI/socket connection. Users can disable review
  97. or enable a timed bypass in the workbench preferences. This does not prevent other
  98. paired clients from sending Python directly to the bridge.
  99. Supported file tools also request local review by default. The dialog shows the
  100. operation and path, and the preferences offer an explicit override for automation.
  101. This is not a filesystem sandbox; see the security guide for connection-mode and
  102. CAM output limitations.
  103. The server now defaults to socket mode so the GUI can show these reviews.
  104. Existing client configurations that explicitly set `FREECAD_MODE=xmlrpc` keep
  105. using XML-RPC; change that setting to `socket` to use local review.
  106. See the [security guide](docs/guide/security.md) for the warning, pairing,
  107. client approvals, file access, and remote-access considerations.
  108. ![FreeCAD with the standalone bridge permissions warning in the status bar](docs/assets/images/bridge-permissions-full.png)
  109. Some MCP clients also request permission before calling an unsafe tool. This
  110. example shows Codex asking to run a harmless Python request against the
  111. isolated test server:
  112. ![Codex permission prompt for an example Python tool call](docs/assets/images/codex-python-permission.png)
  113. The client prompt depends on its settings and is separate from FreeCAD's local
  114. review.
  115. For example, when an agent requests `execute_python`, FreeCAD can show the
  116. complete code and ask the user to allow it once or deny it:
  117. ![FreeCAD review dialog showing harmless example Python and Allow once and Deny buttons](docs/assets/images/bridge-python-review.png)
  118. The Python example was captured in an isolated test profile with an MCP test
  119. client. Starting with version 0.8.0, `run_macro` also requests local
  120. review when unsafe tools are enabled and FreeCAD is connected using a supported
  121. GUI/socket bridge. The dialog displays the macro's path, SHA-256, arguments,
  122. and captured code:
  123. ![FreeCAD macro review dialog showing the path, checksum, code, and approval choices](docs/assets/images/bridge-macro-review.png)
  124. You can allow the request once, deny it, or explicitly save approval for that
  125. path and exact file contents. If enabled in preferences, a time-limited bypass
  126. is also available. Saved approvals bind only the path and file contents; changes
  127. to arguments, imported files, or other dependencies do not require a new review. Manage saved versions in the bridge preferences.
  128. See the [security guide](docs/guide/security.md) for screenshots, limitations,
  129. and the behavior after timeouts.
  130. ## Installation Requirements / Dependencies
  131. - [FreeCAD](https://www.freecad.org/) 1.0.2 or newer is required. FreeCAD 1.1.4
  132. or newer is recommended for security; older releases have known vulnerabilities
  133. when opening untrusted files.
  134. - Python 3.11 or newer for the external server; embedded mode requires a Python
  135. minor version matching FreeCAD's bundled Python.
  136. ---
  137. ## For Users
  138. This section covers installation and usage for end users who want to use the Robust MCP Server with AI assistants.
  139. ### Quick Links
  140. | Resource | Description |
  141. | ------------------------------------------------------------------------------------- | --------------------------------------------- |
  142. | [**Documentation**](https://spkane.github.io/freecad-addon-robust-mcp-server/) | Full documentation, guides, and API reference |
  143. | [Docker Hub](https://hub.docker.com/r/spkane/freecad-robust-mcp) | Pre-built Docker images for easy deployment |
  144. | [PyPI](https://pypi.org/project/freecad-robust-mcp/) | Python package for pip installation |
  145. | [GitHub Releases](https://github.com/spkane/freecad-addon-robust-mcp-server/releases) | Release archives and changelogs |
  146. ## Robust MCP Server
  147. > **Note**: The Linux container and PyPI package are both named `freecad-robust-mcp` which differs slightly from this git repository name.
  148. ### Installation
  149. For the everyday setup, see the [Quick Start](https://spkane.github.io/freecad-addon-robust-mcp-server/latest/getting-started/quickstart/)
  150. for the server, workbench, pairing, and assistant configuration. Install or
  151. update both components to compatible versions; pairing requires 0.7.0 or later.
  152. #### Using pip
  153. ```bash
  154. pip install freecad-robust-mcp
  155. ```
  156. #### Using GitHub release assets
  157. Download the server wheel and matching workbench archive for your chosen release.
  158. The [release asset installation guide](docs/getting-started/installation.md#method-2-github-release-assets)
  159. covers installation, updates, FreeCAD profiles, and release candidates. Install
  160. and update both components; `cam-gate-v1.json` is not needed for installation.
  161. #### Using uv (from source)
  162. Install [Git](https://git-scm.com/install/) and
  163. [uv](https://docs.astral.sh/uv/getting-started/installation/) first.
  164. ```bash
  165. git clone https://github.com/spkane/freecad-addon-robust-mcp-server.git
  166. cd freecad-addon-robust-mcp-server
  167. uv sync --all-extras
  168. ```
  169. #### Using Docker
  170. Run the Robust MCP Server in a container. This is useful for isolated environments or when you don't want to install Python dependencies on your host.
  171. ```bash
  172. # Pull from Docker Hub (when published)
  173. docker pull spkane/freecad-robust-mcp
  174. # Or build locally
  175. git clone https://github.com/spkane/freecad-addon-robust-mcp-server.git
  176. cd freecad-addon-robust-mcp-server
  177. docker build -t freecad-robust-mcp .
  178. # Or use just commands (if you have mise/just installed)
  179. just docker::build # Build for local architecture
  180. just docker::build-multi # Build multi-arch (amd64 + arm64)
  181. ```
  182. The containerized Robust MCP Server only supports `xmlrpc` and `socket`
  183. modes because FreeCAD runs on the host. This topology currently works only
  184. with Docker Desktop, whose `host.docker.internal` forwarding can reach a
  185. host-loopback listener.
  186. The container also needs the existing bridge pairing credential; pairing the
  187. host account does not provision it in the container. A portable secure
  188. provisioning procedure has not yet been validated, so run the MCP server on the
  189. host unless the container credential is already provisioned securely.
  190. > **Security and Linux limitation:** The FreeCAD bridge listens on loopback and
  191. > requires pairing before accepting Python execution. Docker Engine on Linux maps
  192. > `host.docker.internal` or `host-gateway` to a bridge-network address, which
  193. > cannot reach that loopback listener. Run the MCP server directly on the Linux
  194. > host instead. Do not expose ports 9875 or 9876 by rebinding the bridge to
  195. > `0.0.0.0`; protected remote transport is not implemented yet.
  196. ### Configuration
  197. #### Environment Variables
  198. | Variable | Description | Default |
  199. | --------------------- | ---------------------------------------------------- | ----------- |
  200. | `FREECAD_MODE` | Connection mode: `xmlrpc`, `socket`, or `embedded` | `socket` |
  201. | `FREECAD_PATH` | Path to FreeCAD's lib directory (embedded mode only) | Auto-detect |
  202. | `FREECAD_SOCKET_HOST` | Socket/XML-RPC server hostname | `localhost` |
  203. | `FREECAD_SOCKET_PORT` | JSON-RPC socket server port | `9876` |
  204. | `FREECAD_XMLRPC_PORT` | XML-RPC server port | `9875` |
  205. | `FREECAD_TIMEOUT_MS` | Default execution timeout in ms (1000-600000) | `30000` |
  206. `FREECAD_ALLOW_UNREVIEWED_FILE_OPERATIONS=true` explicitly bypasses local file
  207. review for automation; it defaults to `false`.
  208. #### Connection Modes
  209. | Mode | Description | Platform Support |
  210. | ---------- | ------------------------------------------- | --------------------------------- |
  211. | `xmlrpc` | Connects to FreeCAD via XML-RPC (port 9875) | **All platforms** |
  212. | `socket` | Connects via JSON-RPC socket (port 9876) | **All platforms** (recommended) |
  213. | `embedded` | Imports FreeCAD directly into process | **Linux only** (crashes on macOS) |
  214. **Note:** Embedded mode crashes on macOS because FreeCAD's `FreeCAD.so` links to `@rpath/libpython3.11.dylib`, which conflicts with external Python interpreters. Use `xmlrpc` or `socket` mode on macOS and Windows.
  215. #### MCP Client Configuration
  216. Add something like the following to your MCP client settings. For Claude Code, this is `~/.claude/claude_desktop_config.json` or a project `.mcp.json` file:
  217. ```json
  218. {
  219. "mcpServers": {
  220. "freecad": {
  221. "command": "freecad-mcp",
  222. "env": {
  223. "FREECAD_MODE": "socket"
  224. }
  225. }
  226. }
  227. }
  228. ```
  229. If installed from source with mise/uv:
  230. ```json
  231. {
  232. "mcpServers": {
  233. "freecad": {
  234. "command": "/path/to/mise/shims/uv",
  235. "args": ["run", "--project", "/path/to/freecad-addon-robust-mcp-server", "freecad-mcp"],
  236. "env": {
  237. "FREECAD_MODE": "socket"
  238. }
  239. }
  240. }
  241. }
  242. ```
  243. If using Docker Desktop on macOS or Windows:
  244. ```json
  245. {
  246. "mcpServers": {
  247. "freecad": {
  248. "command": "docker",
  249. "args": [
  250. "run", "--rm", "-i",
  251. "-e", "FREECAD_MODE=socket",
  252. "-e", "FREECAD_SOCKET_HOST=host.docker.internal",
  253. "spkane/freecad-robust-mcp"
  254. ]
  255. }
  256. }
  257. }
  258. ```
  259. **Docker configuration notes:**
  260. - `--rm` removes the container after it exits
  261. - `-i` keeps stdin open for MCP communication
  262. - `FREECAD_SOCKET_HOST=host.docker.internal` tells the Robust MCP Server to connect to FreeCAD on your host machine
  263. This example is not supported on Docker Engine for Linux. Its host gateway
  264. cannot reach the bridge's loopback-only listener. `FREECAD_SOCKET_HOST` changes
  265. only the address dialed by the MCP server; it does not change the address on
  266. which the FreeCAD bridge listens.
  267. ### Usage
  268. #### Starting the MCP Bridge in FreeCAD
  269. Before starting the bridge, pair the MCP server and FreeCAD bridge using the
  270. same operating-system user account:
  271. ```bash
  272. freecad-mcp --pair-bridge
  273. ```
  274. For a source checkout use `uv run freecad-mcp --pair-bridge`. For container or
  275. different-account setups, see the [pairing instructions](docs/getting-started/installation.md#step-1-pair-the-bridge).
  276. Install compatible server and workbench releases at version 0.7.0 or later;
  277. 0.6.x releases predate pairing. For development, use both components from the
  278. same source checkout, as described in the installation guide.
  279. Then start the MCP bridge inside FreeCAD:
  280. ##### Option A: Using the Workbench (Recommended)
  281. 1. Install the workbench using the [installation guide](docs/getting-started/installation.md).
  282. The workbench is not currently in the public Addon Manager catalog.
  283. 1. Start the bridge:
  284. - Switch to the Robust MCP Bridge workbench
  285. - Click the **Start MCP Bridge** button in the toolbar
  286. - Or use the menu: **MCP Bridge -> Start Bridge**
  287. 1. You should see in the FreeCAD console:
  288. ```text
  289. MCP Bridge started!
  290. - XML-RPC: localhost:9875
  291. - Socket: localhost:9876
  292. ```
  293. ##### Option B: Using just commands (from source)
  294. ```bash
  295. # Start FreeCAD with MCP bridge auto-started
  296. just freecad::run-gui
  297. # Or for headless/automation mode:
  298. just freecad::run-headless
  299. ```
  300. After starting the bridge, start/restart your MCP client (Claude Code, etc.) - it will connect automatically
  301. #### Uninstalling the MCP Bridge
  302. To uninstall the Robust MCP Bridge workbench:
  303. On Linux or macOS, run `just install::uninstall-mcp-bridge-workbench` from the
  304. checkout to remove a source installation. The command selects the latest
  305. profile; pass the original profile's `Mod` directory if it differs. On Windows,
  306. remove the `RobustMCPBridge` directory from the original profile's `Mod`
  307. directory. For a release archive, remove its extracted package directory from
  308. the original profile's `Mod` directory. Restart FreeCAD afterward.
  309. ##### Checking for Legacy Components
  310. If you previously used older versions of this project, you may have legacy components installed. Run this command to check what's installed and get cleanup instructions:
  311. ```bash
  312. just install::status
  313. ```
  314. ##### Manual Cleanup (if needed)
  315. Check each FreeCAD profile you use for legacy `MCPBridge` workbench folders
  316. and `StartMCPBridge.FCMacro` macro files. Move obsolete copies out of the
  317. profile after confirming they are no longer needed. Profile paths vary by
  318. FreeCAD version; see the [installation guide](docs/getting-started/installation.md#manual-installation-from-a-release-archive)
  319. for how to find the active user data directory.
  320. #### Running Modes
  321. ##### XML-RPC Mode
  322. Connects to a running FreeCAD instance via XML-RPC. Works on all platforms.
  323. ```bash
  324. FREECAD_MODE=xmlrpc freecad-mcp
  325. ```
  326. ##### Socket Mode (Recommended)
  327. Connects via JSON-RPC socket. Works on all platforms.
  328. ```bash
  329. FREECAD_MODE=socket freecad-mcp
  330. ```
  331. ##### Headless Mode
  332. Run FreeCAD in console mode without GUI. Useful for automation.
  333. ```bash
  334. # If installed from source:
  335. just freecad::run-headless
  336. ```
  337. **Note:** Screenshot and view features are not available in headless mode.
  338. ##### Embedded Mode (Linux Only)
  339. Runs FreeCAD in-process. **Only works on Linux** - crashes on macOS/Windows.
  340. ```bash
  341. FREECAD_MODE=embedded freecad-mcp
  342. ```
  343. ### Available Tools
  344. The Robust MCP Server provides **150+ tools** organized into categories. Tools marked with **GUI** require FreeCAD to be running in GUI mode; they will return an error in headless mode.
  345. #### Execution & Debugging (5 tools)
  346. | Tool | Description | Mode |
  347. | ---------------------------- | ------------------------------------------------------------- | ---- |
  348. | `execute_python` | Execute Python; enable unsafe tools and use socket mode | GUI |
  349. | `get_freecad_version` | Get FreeCAD version, build date, and Python version | All |
  350. | `get_connection_status` | Check MCP bridge connection status and latency | All |
  351. | `get_console_output` | Get recent Report view or available console history | All* |
  352. | `get_mcp_server_environment` | Get Robust MCP Server environment (OS, hostname, instance_id) | All |
  353. *Console history depends on FreeCAD session capabilities and is unavailable in
  354. embedded mode; an unavailable source returns an error.*
  355. #### Document Management (7 tools)
  356. | Tool | Description | Mode |
  357. | --------------------- | ----------------------------------------- | ---- |
  358. | `list_documents` | List all open documents with metadata | All |
  359. | `get_active_document` | Get information about the active document | All |
  360. | `create_document` | Create a new FreeCAD document | All |
  361. | `open_document` | Open an existing .FCStd file | All |
  362. | `save_document` | Save a document to disk | All |
  363. | `close_document` | Close a document (with optional save) | All |
  364. | `recompute_document` | Force recomputation of all objects | All |
  365. #### Object Creation - Primitives (8 tools)
  366. | Tool | Description | Mode |
  367. | ----------------- | -------------------------------------------------- | ---- |
  368. | `create_object` | Create a generic FreeCAD object by type ID | All |
  369. | `create_box` | Create a Part::Box with length, width, height | All |
  370. | `create_cylinder` | Create a Part::Cylinder with radius, height, angle | All |
  371. | `create_sphere` | Create a Part::Sphere with radius | All |
  372. | `create_cone` | Create a Part::Cone with two radii and height | All |
  373. | `create_torus` | Create a Part::Torus (donut) with radii and angles | All |
  374. | `create_wedge` | Create a Part::Wedge (tapered box) | All |
  375. | `create_helix` | Create a Part::Helix curve for sweeps and threads | All |
  376. #### Object Management (12 tools)
  377. | Tool | Description | Mode |
  378. | ------------------- | -------------------------------------------------- | ---- |
  379. | `list_objects` | List all objects in a document | All |
  380. | `inspect_object` | Get detailed object info (properties, shape, etc.) | All |
  381. | `edit_object` | Modify properties of an existing object | All |
  382. | `delete_object` | Delete an object from a document | All |
  383. | `set_placement` | Set object position and rotation | All |
  384. | `scale_object` | Scale an object uniformly or non-uniformly | All |
  385. | `rotate_object` | Rotate an object around an axis | All |
  386. | `copy_object` | Create a copy of an object | All |
  387. | `mirror_object` | Mirror an object across a plane (XY, XZ, YZ) | All |
  388. | `boolean_operation` | Fuse, cut, or intersect objects | All |
  389. | `get_selection` | Get currently selected objects | GUI |
  390. | `set_selection` | Select specific objects by name | GUI |
  391. | `clear_selection` | Clear all selections | GUI |
  392. #### PartDesign - Sketching (14 tools)
  393. | Tool | Description | Mode |
  394. | ------------------------ | ----------------------------------------------- | ---- |
  395. | `create_partdesign_body` | Create a PartDesign::Body container | All |
  396. | `create_sketch` | Create a sketch on a plane or face | All |
  397. | `add_sketch_rectangle` | Add a rectangle to a sketch | All |
  398. | `add_sketch_circle` | Add a circle to a sketch | All |
  399. | `add_sketch_line` | Add a line (with optional construction flag) | All |
  400. | `add_sketch_arc` | Add an arc by center, radius, and angles | All |
  401. | `add_sketch_point` | Add a point (useful for hole centers) | All |
  402. | `pad_sketch` | Extrude a sketch (additive) | All |
  403. | `pocket_sketch` | Cut into solid using a sketch (subtractive) | All |
  404. | `revolution_sketch` | Revolve a sketch around an axis (additive) | All |
  405. | `groove_sketch` | Revolve a sketch around an axis (subtractive) | All |
  406. | `create_hole` | Create parametric holes with optional threading | All |
  407. | `loft_sketches` | Create a loft through multiple sketches | All |
  408. | `sweep_sketch` | Sweep a profile along a spine path | All |
  409. #### PartDesign - Patterns & Edges (5 tools)
  410. | Tool | Description | Mode |
  411. | ------------------ | ------------------------------------------ | ---- |
  412. | `linear_pattern` | Create linear pattern of a feature | All |
  413. | `polar_pattern` | Create polar/circular pattern of a feature | All |
  414. | `mirrored_feature` | Mirror a feature across a plane | All |
  415. | `fillet_edges` | Add fillets (rounded edges) | All |
  416. | `chamfer_edges` | Add chamfers (beveled edges) | All |
  417. #### View & Display (11 tools)
  418. | Tool | Description | Mode |
  419. | ----------------------- | ----------------------------------------------- | ---- |
  420. | `get_screenshot` | Capture a screenshot of the 3D view | GUI |
  421. | `set_view_angle` | Set camera to standard views (Front, Top, etc.) | GUI |
  422. | `fit_all` | Zoom to fit all objects in view | GUI |
  423. | `zoom_in` | Zoom in by a factor | GUI |
  424. | `zoom_out` | Zoom out by a factor | GUI |
  425. | `set_camera_position` | Set camera position and look-at point | GUI |
  426. | `set_object_visibility` | Show/hide objects | GUI |
  427. | `set_display_mode` | Set display mode (Shaded, Wireframe, etc.) | GUI |
  428. | `set_object_color` | Set object color as RGB values | GUI |
  429. | `list_workbenches` | List available FreeCAD workbenches | All |
  430. | `activate_workbench` | Switch to a different workbench | All |
  431. #### Undo/Redo (3 tools)
  432. | Tool | Description | Mode |
  433. | ---------------------- | ---------------------------------- | ---- |
  434. | `undo` | Undo the last operation | All |
  435. | `redo` | Redo a previously undone operation | All |
  436. | `get_undo_redo_status` | Get available undo/redo operations | All |
  437. #### Export/Import (7 tools)
  438. | Tool | Description | Mode |
  439. | ------------- | ------------------------------------------ | ---- |
  440. | `export_step` | Export to STEP format (ISO CAD exchange) | All |
  441. | `export_stl` | Export to STL format (3D printing) | All |
  442. | `export_3mf` | Export to 3MF format (modern 3D printing) | All |
  443. | `export_obj` | Export to OBJ format (Wavefront) | All |
  444. | `export_iges` | Export to IGES format (older CAD exchange) | All |
  445. | `import_step` | Import a STEP file | All |
  446. | `import_stl` | Import an STL file as mesh | All |
  447. #### Macro Management (6 tools)
  448. | Tool | Description | Mode |
  449. | ---------------------------- | ---------------------------------------------- | ---- |
  450. | `list_macros` | List all available FreeCAD macros | All |
  451. | `run_macro` | Run a macro with local review (socket only) | GUI |
  452. | `create_macro` | Create a new macro file | All |
  453. | `read_macro` | Read macro source code | All |
  454. | `delete_macro` | Delete a user macro | All |
  455. | `create_macro_from_template` | Create macro from template (basic, part, etc.) | All |
  456. #### Parts Library (2 tools)
  457. | Tool | Description | Mode |
  458. | -------------------------- | ------------------------------------- | ---- |
  459. | `list_parts_library` | List parts in FreeCAD's parts library | All |
  460. | `insert_part_from_library` | Insert a part from the library | All |
  461. ---
  462. ## For Developers
  463. This section covers development setup, contributing, and working with the codebase.
  464. ## Robust MCP Server Development
  465. ### Prerequisites
  466. - [mise](https://mise.jdx.dev/) - Tool version manager
  467. - [FreeCAD](https://www.freecad.org/) 1.1.4 or newer is recommended for security.
  468. ### Initial Setup
  469. ```bash
  470. # Clone the repository
  471. git clone https://github.com/spkane/freecad-addon-robust-mcp-server.git
  472. cd freecad-addon-robust-mcp-server
  473. # Install mise via the Official mise installer script (if not already installed)
  474. curl https://mise.run | sh
  475. # Install all tools (Python 3.11, uv, just, pre-commit)
  476. mise trust
  477. mise install
  478. # Set up the development environment
  479. just setup
  480. ```
  481. This installs:
  482. - **Python 3.11** - Required for FreeCAD ABI compatibility
  483. - **uv** - Fast Python package manager
  484. - **just** - Command runner for development workflows
  485. - **pre-commit** - Git hooks for code quality
  486. ### MCP Client Configuration (Development)
  487. Create a `.mcp.json` file in the project directory:
  488. ```json
  489. {
  490. "mcpServers": {
  491. "freecad": {
  492. "command": "/path/to/mise/shims/uv",
  493. "args": ["run", "--project", "/path/to/freecad-addon-robust-mcp-server", "freecad-mcp"],
  494. "env": {
  495. "FREECAD_MODE": "socket",
  496. "FREECAD_SOCKET_HOST": "localhost",
  497. "FREECAD_SOCKET_PORT": "9876",
  498. "PATH": "/path/to/mise/shims:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
  499. }
  500. }
  501. }
  502. }
  503. ```
  504. **Replace the paths with your actual paths:**
  505. | Placeholder | Description | Example |
  506. | ------------------------------------------- | ------------------------------- | ---------------------------------------------- |
  507. | `/path/to/mise/shims/uv` | Full path to uv via mise shims | `~/.local/share/mise/shims/uv` |
  508. | `/path/to/freecad-addon-robust-mcp-server` | Project directory | `/home/me/dev/freecad-addon-robust-mcp-server` |
  509. | `/path/to/mise/shims` | mise shims directory for PATH | `~/.local/share/mise/shims` |
  510. **Finding your mise shims path:**
  511. ```bash
  512. mise where uv | sed 's|/installs/.*|/shims|'
  513. # Example: /home/user/.local/share/mise/shims (on Linux) or ~/.local/share/mise/shims (on macOS)
  514. ```
  515. ### Development Workflow
  516. Commands are organized into modules. Use `just` to see top-level commands, or `just list-<module>` to see module-specific commands.
  517. ```bash
  518. # Show top-level commands and available modules
  519. just
  520. # Show commands in a specific module
  521. just list-mcp # Robust MCP Server commands
  522. just list-freecad # FreeCAD plugin/macro commands
  523. just list-install # Installation commands
  524. just list-quality # Code quality commands
  525. just list-testing # Test commands
  526. just list-docker # Docker commands
  527. just list-documentation # Documentation commands
  528. just list-dev # Development utilities
  529. # List ALL commands from all modules
  530. just list-all
  531. # Install/update dependencies
  532. just install::mcp-server
  533. # Run all checks (linting, type checking, tests)
  534. just all
  535. # Quality commands
  536. just quality::lint # Run ruff linter
  537. just quality::typecheck # Run mypy type checker
  538. just quality::format # Format code
  539. just quality::check # Run all pre-commit hooks
  540. # Testing commands
  541. just testing::unit # Run unit tests
  542. just testing::cov # Run tests with coverage
  543. just testing::integration # Run integration tests
  544. # Run the Robust MCP Server (or with debug logging)
  545. just mcp::run
  546. just mcp::run-debug
  547. # Docker commands
  548. just docker::build # Build image for local architecture
  549. just docker::build-multi # Build multi-arch image (amd64 + arm64)
  550. just docker::run # Run container
  551. ```
  552. ### Running FreeCAD with the MCP Bridge
  553. #### GUI Mode (recommended for development)
  554. ```bash
  555. # Start FreeCAD with auto-started bridge
  556. just freecad::run-gui
  557. ```
  558. #### Headless Mode (for automation/CI)
  559. ```bash
  560. just freecad::run-headless
  561. ```
  562. ### Running Tests
  563. ```bash
  564. # Unit tests only (no FreeCAD required)
  565. just testing::unit
  566. # Unit tests with coverage
  567. just testing::cov
  568. # Integration tests (requires running FreeCAD bridge)
  569. just testing::integration
  570. # Integration tests with automatic FreeCAD startup
  571. just testing::integration-auto
  572. ```
  573. ### Code Quality
  574. The project uses strict code quality checks via pre-commit:
  575. - **Ruff** - Linting and formatting
  576. - **MyPy** - Type checking
  577. - **Bandit** - Security scanning
  578. - **Codespell** - Spell checking
  579. - **Secrets scanning** - Gitleaks, detect-secrets, TruffleHog
  580. ```bash
  581. # Run all pre-commit hooks
  582. just quality::check
  583. # Run security/secrets scans
  584. just quality::security
  585. just quality::secrets
  586. ```
  587. ---
  588. ## Architecture
  589. See the [detailed architecture document](docs/development/architecture-detailed.md) for design documentation covering:
  590. - Module structure
  591. - Bridge communication protocols
  592. - Tool registration patterns
  593. - FreeCAD plugin architecture
  594. ---
  595. ## Acknowledgements
  596. This project was developed after analyzing several existing FreeCAD Robust MCP implementations. We are grateful to these projects for their pioneering work and the ideas they contributed to the FreeCAD + AI ecosystem:
  597. ### Related Projects
  598. - **[neka-nat/freecad-mcp](https://github.com/neka-nat/freecad-mcp)** (MIT License) - The queue-based thread safety pattern and XML-RPC protocol design (port 9875) were directly inspired by this project. Our implementation maintains protocol compatibility while being a complete rewrite with additional features.
  599. - **[jango-blockchained/mcp-freecad](https://github.com/jango-blockchained/mcp-freecad)** - Inspired our connection recovery mechanisms and multi-mode architecture approach.
  600. - **[contextform/freecad-mcp](https://github.com/contextform/freecad-mcp)** - Informed our comprehensive PartDesign and Part workbench tool coverage.
  601. - **[ATOI-Ming/FreeCAD-MCP](https://github.com/ATOI-Ming/FreeCAD-MCP)** - Inspired our macro development toolkit including templates, validation, and automatic imports.
  602. - **[bonninr/freecad_mcp](https://github.com/bonninr/freecad_mcp)** - Influenced our simple socket-based communication approach.
  603. See [docs/COMPARISON.md](docs/COMPARISON.md) for a detailed analysis of these implementations and the design decisions they informed.
  604. ---
  605. ## License
  606. Code is distributed under [Apache License 2.0](LICENSE-CODE); previously
  607. MIT-licensed contributions retain their [original MIT terms](LICENSE-MIT).
  608. Workbench icons use [CC BY-SA 4.0](LICENSE-ICON). See [NOTICE](NOTICE) for
  609. attribution.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.