Skip to content
Back to search

FreeCAD-MCP

FreeCAD plugin for automating model creation and control via Model Contro Protocol (MCP). Provides a MCP server,GUl panel, and client for running macros,managing documents, and adjusting views.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/atoi-ming--freecad-mcp/badge.svg)](/listings/atoi-ming--freecad-mcp)

HTML

<a href="/listings/atoi-ming--freecad-mcp"><img src="/api/listings/atoi-ming--freecad-mcp/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.

1. Install the plugin (see [Installation](#installation)). 2. Launch FreeCAD and switch to the `FreeCAD MCP` workbench. 3. Open the control panel (`FreeCAD_MCP_Show`) and click "Start Server." 4. Run an example macro:

   python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro gear.FCMacro --params '{"radius": 15}'

5. View the result: A gear model is generated and displayed in axonometric view.

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 · 329 lines

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

  1. # FreeCAD MCP Plugin
  2. The **FreeCAD MCP** plugin integrates the **Model Control Protocol (MCP)** into FreeCAD, enabling automation of model creation, macro execution, and view management through a server-client architecture. It provides a GUI control panel and a command-line client to streamline FreeCAD workflows, supporting tasks like creating/running macros, adjusting views, and integrating with external tools (e.g., Claude, Cursor, Trace, CodeBuddy).
  3. ![FreeCAD MCP Icon](assets/icon.svg)
  4. ## Table of Contents
  5. - [Features](#features)
  6. - [Quick Start](#quick-start)
  7. - [Installation](#installation)
  8. - [MCP Configuration](#mcp-configuration)
  9. - [Usage](#usage)
  10. - [Tool Functions](#tool-functions)
  11. - [Use Cases](#use-cases)
  12. - [External Tool Integration](#external-tool-integration)
  13. - [Assets](#assets)
  14. - [Troubleshooting](#troubleshooting)
  15. - [Contributing](#contributing)
  16. - [License](#license)
  17. ## Features
  18. The FreeCAD MCP plugin (v0.1.0) offers the following features:
  19. - **MCP Server**: Provides a GUI control panel (`FreeCADMCPPanel`) and processes commands like `create_macro`, `update_macro`, `run_macro`, `set_view`, and `get_report` (implemented in `freecad_mcp_server.py`).
  20. - **MCP Client**: Command-line tool to send commands via `stdio` or TCP, manage `.FCMacro` files (create, update, run, validate), and control FreeCAD remotely (implemented in `freecad_mcp_client.py`).
  21. - **Macro Normalization**: Automatically adds imports (`FreeCAD`, `FreeCADGui`, `Part`, `math`) and post-execution steps (recompute, view adjustment) for macros.
  22. - **GUI Control Panel**: Includes buttons to start/stop the server, clear logs, and switch views (front, top, right, axonometric).
  23. - **Logging System**: Records messages and errors to `freecad_mcp_log.txt` in the temporary directory (e.g., `%TEMP%\freecad_mcp_log.txt`) and a GUI report browser (100-line limit).
  24. - **Workbench Integration**: Adds a `FreeCADMCPWorkbench` with toolbar and menu commands (implemented in `InitGui.py`).
  25. - **Visual Assets**: Includes workbench icon (`icon.svg`), example models (`gear.png`, `flange.png`, `boat.png`, `table.png`), and demo animation (`freecad.gif`, `freecad.mp4`).
  26. Watch the demo animation:
  27. <img src="https://raw.githubusercontent.com/ATOI-Ming/FreeCAD-MCP/main/assets/freecad.gif" width="900">
  28. Download the demo video: [FreeCAD MCP Demo MP4](assets/freecad.mp4)
  29. ## Quick Start
  30. 1. Install the plugin (see [Installation](#installation)).
  31. 2. Launch FreeCAD and switch to the `FreeCAD MCP` workbench.
  32. 3. Open the control panel (`FreeCAD_MCP_Show`) and click "Start Server."
  33. 4. Run an example macro:
  34. ```bash
  35. python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro gear.FCMacro --params '{"radius": 15}'
  36. ```
  37. 5. View the result: A gear model is generated and displayed in axonometric view.
  38. ## Installation
  39. ### Prerequisites
  40. - **FreeCAD**: Version 0.21 or higher, [Download FreeCAD](https://www.freecad.org/downloads.php?lang=zh_CN). Select the version for your operating system.
  41. - **Python**: Version 3.12+ (included with FreeCAD or installed via Anaconda).
  42. - **Anaconda** (recommended for dependency management): [Download Anaconda](https://www.anaconda.com/download). Select the version for your operating system.
  43. - **Python Dependencies**:
  44. - Required packages: `mcp-server` (specified in `pyproject.toml`).
  45. - Installation commands:
  46. ```bash
  47. # use system Python
  48. pip install mcp-server
  49. ```
  50. - Verify installation:
  51. ```bash
  52. pip show mcp-server
  53. ```
  54. Ensure `mcp-server` version .
  55. ### Installation Steps
  56. 1. **Clone the Repository**:
  57. ```bash
  58. git clone https://github.com/ATOI-Ming/FreeCAD-MCP.git
  59. ```
  60. 2. **Copy to FreeCAD Mod Directory**:
  61. Copy the `FreeCAD-MCP` folder to:
  62. - Windows: `D:\FreeCAD\Mod\FreeCAD-MCP`
  63. - Linux: `~/.local/share/FreeCAD/Mod/FreeCAD-MCP`
  64. - macOS: `~/Library/Application Support/FreeCAD/Mod/FreeCAD-MCP`
  65. ```bash
  66. # Windows example
  67. xcopy FreeCAD-MCP D:\FreeCAD\Mod\FreeCAD-MCP /E /H /C /I
  68. ```
  69. **Note**: Adjust `D:\FreeCAD\Mod` based on your FreeCAD installation path.
  70. 3. **Launch FreeCAD**:
  71. - Open FreeCAD and switch to the `FreeCAD MCP` workbench (icon: `assets/icon.svg`).
  72. - Verify that `FreeCAD-MCP` is loaded in **Edit > Preferences > Add-ons**.
  73. 4. **Verify Installation**:
  74. - Click `FreeCAD_MCP_Show` to open the control panel.
  75. - Check the temporary directory (e.g., `%TEMP%\freecad_mcp_log.txt`) for startup messages.
  76. ## MCP Configuration
  77. Configure the MCP client to communicate with FreeCAD via `stdio` or TCP.
  78. 1. **Create Configuration File**:
  79. Create `mcp_config.json` in `D:\FreeCAD\Mod\FreeCAD-MCP-main\src\`:
  80. ```json
  81. {
  82. "mcpServers": {
  83. "freecad": {
  84. "disabled": false,
  85. "timeout": 60,
  86. "type": "stdio",
  87. "command": "D:\\Anaconda3\\python.exe",
  88. "args": ["D:\\FreeCAD\\Mod\\FreeCAD-MCP-main\\src\\freecad_mcp_client.py"]
  89. }
  90. }
  91. }
  92. ```
  93. **Note**:
  94. - Adjust paths based on your system:
  95. - **Anaconda Path**: e.g., `C:\Anaconda3\python.exe` (Windows), `/home/<user>/anaconda3/bin/python` (Linux), `/Users/<user>/anaconda3/bin/python` (macOS).
  96. - **FreeCAD Mod Path**: e.g., `C:\Users\<YourUser>\AppData\Roaming\FreeCAD\Mod\FreeCAD-MCP` (Windows), `/home/<user>/.local/share/FreeCAD/Mod/FreeCAD-MCP` (Linux), `/Users/<user>/Library/Application Support/FreeCAD/Mod/FreeCAD-MCP` (macOS).
  97. - For TCP communication, set `"type": "tcp"`, add `"host": "localhost"`, and `"port": 9876`.
  98. 2. **Run the Server**:
  99. - **GUI Method**: In the `FreeCAD MCP` workbench, click `FreeCAD_MCP_Show` and then "Start Server."
  100. - **Command-Line Method**:
  101. ```bash
  102. conda activate freecad_mcp
  103. python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_server.py
  104. ```
  105. 3. **Verify Server**:
  106. - Check `%TEMP%\freecad_mcp_log.txt` for a "Server started" message.
  107. - Test a client command:
  108. ```bash
  109. python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --get-report
  110. ```
  111. ## Usage
  112. ### GUI Usage
  113. 1. In FreeCAD, switch to the `FreeCAD MCP` workbench (icon: `assets/icon.svg`).
  114. 2. Click `FreeCAD_MCP_Show` to open the control panel (`FreeCADMCPPanel`).
  115. 3. Use the control panel:
  116. - **Start/Stop Server**: Control the MCP server.
  117. - **Clear Logs**: Clear the report browser and `%TEMP%\freecad_mcp_log.txt`.
  118. - **View Switching**: Select front, top, right, or axonometric views.
  119. 4. Run a macro:
  120. - Click `FreeCAD_MCP_RunMacro`, select an `.FCMacro` file, and execute it with automatic normalization.
  121. ### Command-Line Usage
  122. 1. Activate the Anaconda environment:
  123. ```bash
  124. conda activate freecad_mcp
  125. ```
  126. 2. Run client commands:
  127. ```bash
  128. python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py <command>
  129. ```
  130. Examples:
  131. - Create macro: `--create-macro my_macro --template-type part`
  132. - Run macro: `--run-macro my_macro.FCMacro --params '{"radius": 10}'`
  133. - Set view: `--set-view '{"view_type": "7"}'`
  134. - Get report: `--get-report`
  135. ## Tool Functions
  136. The following tool functions are provided by `freecad_mcp_client.py`, sending commands via `stdio` or TCP (`localhost:9876`), processed by `freecad_mcp_server.py`.
  137. | Function | Parameters | Description |
  138. |-----------------------|-----------------------------------------|----------------------------------------------------------------------|
  139. | `create_macro` | `macro_name`, `template_type` | Creates an `.FCMacro` file, validates name (letters, numbers, underscores, hyphens), supports templates (`default`, `basic`, `part`, `sketch`). |
  140. | `update_macro` | `macro_name`, `code` | Updates macro content, auto-adds `FreeCAD`, `FreeCADGui`, `Part`, `math` imports. |
  141. | `run_macro` | `macro_path`, `params` (optional) | Runs a macro, normalizes code, recomputes document, adjusts to axonometric view. |
  142. | `validate_macro_code` | `macro_name` (optional), `code` (optional) | Validates macro code syntax, returns success or error (with traceback). |
  143. | `set_view` | `params` (e.g., `{"view_type": "7"}`) | Sets view: `1` (front), `2` (top), `3` (right), `7` (axonometric). |
  144. | `get_report` | None | Retrieves server logs (from `%TEMP%\freecad_mcp_log.txt` and report browser). |
  145. ### Examples
  146. - **Create Macro**:
  147. ```bash
  148. python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --create-macro gear --template-type part
  149. ```
  150. Output: `{"status": "success", "result": "Macro created"}`
  151. - **Update Macro**:
  152. ```bash
  153. python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --update-macro gear --code "import FreeCAD, Part\nradius = 10\ngear = Part.makeCylinder(radius, 5)\nPart.show(gear)"
  154. ```
  155. Output: `{"status": "success", "result": "Macro updated"}`
  156. - **Run Macro**:
  157. ```bash
  158. python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro gear.FCMacro --params '{"radius": 15}'
  159. ```
  160. Output: `{"status": "success", "result": {...}}`
  161. - **Validate Code**:
  162. ```bash
  163. python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --validate-macro-code gear --code "import FreeCAD\nApp.newDocument()"
  164. ```
  165. Output: `{"status": "success"}`
  166. - **Set View**:
  167. ```bash
  168. python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --set-view '{"view_type": "7"}'
  169. ```
  170. Output: `{"status": "success", "result": "view set to axonometric"}`
  171. - **Get Report**:
  172. ```bash
  173. python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --get-report
  174. ```
  175. Output: `{"status": "success", "result": {...}}`
  176. ## Use Cases
  177. 1. **Automated Gear Model Creation**:
  178. - **Scenario**: Generate a parametric gear model for engineering design.
  179. - **Steps**:
  180. 1. Create macro: `--create-macro gear --template-type part`
  181. 2. Update macro: `--update-macro gear --code "import FreeCAD, Part\nradius = 15\ngear = Part.makeCylinder(radius, 5)\nPart.show(gear)"`
  182. 3. Run macro: `--run-macro gear.FCMacro --params '{"radius": 15}'`
  183. - **Result**: Gear model generated, displayed in axonometric view.
  184. - **Output**:
  185. ![Gear Model](assets/gear.png)
  186. 2. **Generating a Flange Model**:
  187. - **Scenario**: Automate creation of a flange with holes for mechanical design.
  188. - **Steps**: Run macro: `--run-macro flange.FCMacro`
  189. - **Result**: Flange model generated with automatic normalization.
  190. - **Output**:
  191. ![Flange Model](assets/flange.png)
  192. 3. **Text-Based Model Generation**:
  193. - **Scenario**: Generate a boat model from a text description (e.g., "create a boat with a curved hull").
  194. - **Steps**:
  195. 1. Use Claude to generate `boat.FCMacro`.
  196. 2. Run macro: `--run-macro boat.FCMacro`
  197. - **Result**: Boat model generated with automatic view adjustment.
  198. - **Output**:
  199. ![Boat Model](assets/boat.png)
  200. 4. **CAD Drawing Recognition**:
  201. - **Scenario**: Recreate a table model from a CAD drawing.
  202. - **Steps**:
  203. 1. Use Trace to convert drawing to `table.FCMacro`.
  204. 2. Run macro: `--run-macro table.FCMacro`
  205. - **Result**: Table model generated.
  206. - **Output**:
  207. ![Table Model](assets/table.png)
  208. 5. **Batch Processing Models**:
  209. - **Scenario**: Automate creation of multiple models (e.g., gear and flange).
  210. - **Steps**:
  211. ```bash
  212. for macro in gear.FCMacro flange.FCMacro; do
  213. python D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py --run-macro $macro
  214. done
  215. ```
  216. - **Result**: Models generated sequentially, logged to `%TEMP%\freecad_mcp_log.txt`.
  217. - **Output**: See `gear.png` and `flange.png`.
  218. ## External Tool Integration
  219. FreeCAD MCP supports integration with external tools to enhance model generation:
  220. - **Claude**: AI model for generating `.FCMacro` files from text descriptions.
  221. - **Example**: Input "create a gear with 10mm radius," generates:
  222. ```python
  223. import FreeCAD, Part
  224. radius = 10
  225. gear = Part.makeCylinder(radius, 5)
  226. Part.show(gear)
  227. ```
  228. Save as `gear.FCMacro`, run: `--run-macro gear.FCMacro`.
  229. - **Trace**: CAD drawing processing tool to convert drawings to `.FCMacro` files.
  230. - **Example**: Convert a table drawing to `table.FCMacro`, run: `--run-macro table.FCMacro`.
  231. - **Cursor/CodeBuddy**: Code editing tools for writing and debugging macro code.
  232. - **Example**: Edit `flange.FCMacro` in Cursor, update: `--update-macro flange.FCMacro --code "<code>"`.
  233. ## Assets
  234. The `assets/` directory contains the following resources:
  235. - **icon.svg**: Icon for `FreeCADMCPWorkbench`, used in `InitGui.py` and `package.xml`.
  236. ![FreeCAD MCP Icon](assets/icon.svg)
  237. - **gear.png**: Example gear model.
  238. ![Gear Model](assets/gear.png)
  239. - **flange.png**: Example flange model.
  240. ![Flange Model](assets/flange.png)
  241. - **boat.png**: Example boat model.
  242. ![Boat Model](assets/boat.png)
  243. - **table.png**: Example table model.
  244. ![Table Model](assets/table.png)
  245. - **freecad.gif**: Demo animation showing GUI panel, macro execution, and view switching.
  246. ![Demo Animation](https://raw.githubusercontent.com/ATOI-Ming/FreeCAD-MCP/main/assets/freecad.gif)
  247. - **freecad.mp4**: Demo video, available for download.
  248. Download: [FreeCAD MCP Demo MP4](assets/freecad.mp4)
  249. ## Troubleshooting
  250. - **Server Fails to Start**:
  251. - **Issue**: Port 9876 is in use.
  252. - **Solution**: Check port (`netstat -ano | findstr 9876`), change port, or terminate conflicting process.
  253. - **Client Connection Failure**:
  254. - **Issue**: Incorrect paths in `mcp_config.json`.
  255. - **Solution**: Verify `command` and `args` paths, e.g., `D:\Anaconda3\python.exe` and `D:\FreeCAD\Mod\FreeCAD-MCP-main\src\freecad_mcp_client.py`.
  256. - **Macro Execution Errors**:
  257. - **Issue**: Syntax errors or missing imports in macro code.
  258. - **Solution**: Use `--validate-macro-code` to check code, review traceback in `%TEMP%\freecad_mcp_log.txt`.
  259. - **Log File Not Generated**:
  260. - **Issue**: No write permission in temporary directory.
  261. - **Solution**: Check permissions for `%TEMP%\freecad_mcp_log.txt`, or specify another path in `freecad_mcp_server.py`.
  262. - **More Help**: Submit issues on GitHub ([Bug Tracker](https://github.com/ATOI-Ming/FreeCAD-MCP/issues)).
  263. ## Contributing
  264. Contributions are welcome! Follow these steps:
  265. 1. Fork the repository: `https://github.com/ATOI-Ming/FreeCAD-MCP`.
  266. 2. Create a branch: `git checkout -b feature/your-feature`.
  267. 3. Commit changes: `git commit -m "Add your feature"`.
  268. 4. Push and create a Pull Request.
  269. For questions or collaborations, please open an issue or contact [1757772673@qq.com,抖音:huhushuxue95]
  270. ## License
  271. This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

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