Skip to content
Back to search

freecad-mcp

FreeCAD MCP - Open-source Model Context Protocol server for FreeCAD automation

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/contextform--freecad-mcp/badge.svg)](/listings/contextform--freecad-mcp)

HTML

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

**Windows:**

python -m pip install --user mcp
npm install -g freecad-mcp-setup@latest
npx freecad-mcp-setup setup

**macOS/Linux:**

pip install mcp
npm install -g freecad-mcp-setup@latest
npx freecad-mcp-setup setup

**That's it!** The installer automatically: - ✅ **Cross-platform**: Works on macOS, Linux, and Windows - ✅ Detects your OS and FreeCAD installation - ✅ Downloads latest FreeCAD MCP from GitHub - ✅ Installs the AI Copilot workbench to correct location - ✅ Downloads and registers MCP bridge server - ✅ Provides clear next steps for testing

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 · 253 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 - AI-Powered CAD
  2. **Control FreeCAD with Claude AI through natural language!**
  3. Create 3D models, add features, and automate CAD workflows using conversational AI.
  4. ## 🎥 See It In Action
  5. Watch FreeCAD MCP model a house from a simple text command:
  6. [demo-house-modeling.mp4](https://github.com/contextform/freecad-mcp/blob/main/demo-house-modeling.mp4)
  7. *"Ask FreeCAD to model a house" - and watch it create walls, roof, windows, and door automatically!*
  8. > **🎉 New!** Easy 2-command installation with automatic updates!
  9. ## 📋 Requirements
  10. **Before installation, make sure you have:**
  11. - **FreeCAD 1.0+** - [Download here](https://freecad.org/downloads.php)
  12. - **Node.js & npm** - [Download here](https://nodejs.org/)
  13. - **Claude Code** - `npm install -g claude-code` (recommended)
  14. *Python 3.9+ is included with FreeCAD automatically*
  15. ## ⚡ Super Easy Install
  16. ### 🚀 Quick Install
  17. **Windows:**
  18. ```cmd
  19. python -m pip install --user mcp
  20. npm install -g freecad-mcp-setup@latest
  21. npx freecad-mcp-setup setup
  22. ```
  23. **macOS/Linux:**
  24. ```bash
  25. pip install mcp
  26. npm install -g freecad-mcp-setup@latest
  27. npx freecad-mcp-setup setup
  28. ```
  29. **That's it!** The installer automatically:
  30. - ✅ **Cross-platform**: Works on macOS, Linux, and Windows
  31. - ✅ Detects your OS and FreeCAD installation
  32. - ✅ Downloads latest FreeCAD MCP from GitHub
  33. - ✅ Installs the AI Copilot workbench to correct location
  34. - ✅ Downloads and registers MCP bridge server
  35. - ✅ Provides clear next steps for testing
  36. ### 📦 Updating
  37. **To update to the latest version:**
  38. **Windows:**
  39. ```cmd
  40. npm update -g freecad-mcp-setup
  41. npx freecad-mcp-setup setup
  42. ```
  43. **macOS/Linux:**
  44. ```bash
  45. npm update -g freecad-mcp-setup
  46. npx freecad-mcp-setup setup
  47. ```
  48. The installer will automatically download and install the latest FreeCAD MCP files!
  49. ## 🚀 How to Use
  50. ### Step 1: Start FreeCAD
  51. 1. Launch FreeCAD
  52. 2. The AI Copilot service starts automatically
  53. ### Step 2: Open Claude
  54. In a new terminal/command prompt:
  55. ```bash
  56. claude
  57. ```
  58. ### Step 3: Verify Connection
  59. Ask Claude:
  60. ```
  61. Check FreeCAD connection
  62. ```
  63. You should see confirmation that FreeCAD tools are available.
  64. ### Step 4: Start Creating!
  65. Just ask Claude to design anything - watch the demo video above to see it model a house!
  66. ### 🖥️ Using Claude Desktop?
  67. The installer works with Claude Code by default. For Claude Desktop users, after running the installer, you'll need to manually configure:
  68. **Add to your Claude Desktop config:**
  69. *macOS/Linux:*
  70. ```json
  71. {
  72. "mcpServers": {
  73. "freecad": {
  74. "command": "python3",
  75. "args": ["/Users/yourusername/.freecad-mcp/working_bridge.py"]
  76. }
  77. }
  78. }
  79. ```
  80. *Windows:*
  81. ```json
  82. {
  83. "mcpServers": {
  84. "freecad": {
  85. "command": "python3",
  86. "args": ["C:\\Users\\yourusername\\.freecad-mcp\\working_bridge.py"]
  87. }
  88. }
  89. }
  90. ```
  91. *Config file locations:*
  92. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  93. - **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
  94. ### 🔧 Manual Installation (Developers)
  95. **For developers who prefer full control:**
  96. ```bash
  97. # Clone the repository
  98. git clone https://github.com/contextform/freecad-mcp.git
  99. cd freecad-mcp
  100. # Install dependencies
  101. python3 -m pip install mcp
  102. # Install FreeCAD workbench (choose your OS):
  103. # macOS:
  104. cp -r AICopilot ~/Library/Application\ Support/FreeCAD/Mod/
  105. # Linux:
  106. # cp -r AICopilot ~/.local/share/FreeCAD/Mod/
  107. # Windows:
  108. # cp -r AICopilot %APPDATA%\FreeCAD\Mod\
  109. # Register MCP server with full path
  110. claude mcp add freecad python3 "$(pwd)/working_bridge.py"
  111. ```
  112. ## 🚀 What You Can Do
  113. **Create 3D Objects:**
  114. ```
  115. Create a 50x30x20mm box with 5mm fillets
  116. Make a cylinder with 25mm radius and 60mm height
  117. ```
  118. **Parametric Features:**
  119. ```
  120. Add a 3mm fillet to Pad001
  121. Create a 6mm counterbore hole at position (20,10)
  122. Make a linear pattern of 5 copies spaced 30mm apart
  123. ```
  124. **Advanced Operations:**
  125. ```
  126. Create a PartDesign pad from Sketch001 with 15mm length
  127. Add a mirror of Feature001 across the XZ plane
  128. Take an isometric screenshot at 1200x800
  129. ```
  130. ## 🛠️ Available Operations
  131. - **PartDesign (13 ops)**: Pad, Revolution, Fillet, Chamfer, Holes, Patterns
  132. - **Part (18 ops)**: Primitives, Booleans, Transforms, Advanced shapes
  133. - **View Control (14 ops)**: Screenshots, Zoom, Selection, Document management
  134. - **Python Execution**: Custom FreeCAD scripts for complex operations
  135. ## 🐛 Troubleshooting
  136. **Installation Problems:**
  137. ```bash
  138. # Re-run the installer (fixes most issues)
  139. freecad-mcp setup
  140. # Force update to latest version
  141. freecad-mcp setup --update
  142. # Get help
  143. freecad-mcp --help
  144. ```
  145. **Common Issues:**
  146. | Problem | Solution |
  147. |---------|----------|
  148. | **"FreeCAD not found"** | Install FreeCAD 1.0+ from [freecad.org](https://freecad.org/downloads.php) |
  149. | **"Claude Code not found"** | Run `npm install -g claude-code` |
  150. | **"npm command not found"** | Install Node.js from [nodejs.org](https://nodejs.org/) |
  151. | **MCP registration failed** | Manual setup: `claude mcp add freecad python3 ~/.freecad-mcp/working_bridge.py` |
  152. **Testing Connection:**
  153. 1. Launch FreeCAD first (AI service auto-starts)
  154. 2. Run `claude` in terminal
  155. 3. Ask Claude: **"List available tools"**
  156. 4. Should see `mcp__freecad__*` tools listed ✅
  157. ## 🗑️ Uninstall
  158. To completely remove FreeCAD MCP and restore defaults:
  159. **Windows:**
  160. ```cmd
  161. # Remove from Claude
  162. claude mcp remove freecad
  163. # Remove FreeCAD workbench
  164. rmdir /s /q "%APPDATA%\FreeCAD\Mod\AICopilot"
  165. # Remove MCP files
  166. rmdir /s /q "%USERPROFILE%\.freecad-mcp"
  167. del "%USERPROFILE%\.freecad-mcp-version"
  168. # Uninstall npm package
  169. npm uninstall -g freecad-mcp-setup
  170. ```
  171. **macOS/Linux:**
  172. ```bash
  173. # Remove from Claude
  174. claude mcp remove freecad
  175. # Remove FreeCAD workbench
  176. rm -rf ~/.local/share/FreeCAD/Mod/AICopilot # Linux
  177. # rm -rf ~/Library/Application\ Support/FreeCAD/Mod/AICopilot # macOS
  178. # Remove MCP files
  179. rm -rf ~/.freecad-mcp
  180. rm -f ~/.freecad-mcp-version
  181. # Uninstall npm package
  182. npm uninstall -g freecad-mcp-setup
  183. ```
  184. **Claude Desktop users:** Also remove the "freecad" section from your `claude_desktop_config.json` file.
  185. ---
  186. **Ready to design with AI? Install and start creating!** 🚀

Ratings and comments

Sign in to rate this skill.

Sign in

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