Sean P. KaneandGitHub
f14ab8177d
* chore: rename workbench to FreecadRobustMCPBridge * fix: stdio cleanup and bug fix for JSON RPC * fix: update FreeCAD MCP bridge and tests * test: Fix GUI Integration tests and other issues * fix: unit tests in CI and a few other things * docs: generate GitHub pages site and link to it. * fix: General code improvements and DRY refactoring * chore: General cleanup * chore: small fixes * docs: cleanup * docs: fixes * docs: small corrections * docs: fix * test: release check * bump: workbench v0.6.0 * chore: bump macros to 0.6.0 * docs: Release improvements * refactor: improve DRYness of code
486 lines
12 KiB
Markdown
486 lines
12 KiB
Markdown
# FreeCAD Robust MCP User Guide
|
|
|
|
This guide explains how to use AI assistants with FreeCAD via the MCP (Model Context Protocol) server to create and manipulate 3D CAD models.
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Getting Started](#getting-started)
|
|
1. [Running Modes](#running-modes)
|
|
1. [Basic Workflows](#basic-workflows)
|
|
1. [Object Creation Examples](#object-creation-examples)
|
|
1. [PartDesign Workflow](#partdesign-workflow)
|
|
1. [Complete Example: Mounting Bracket](#complete-example-mounting-bracket)
|
|
1. [Tips and Best Practices](#tips-and-best-practices)
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
1. **FreeCAD installed** - Version 1.0.x or later
|
|
1. **An MCP client** (Claude Code, or other MCP-compatible AI assistant) configured
|
|
1. **Python 3.11** - Must match FreeCAD's bundled Python version
|
|
|
|
### Starting FreeCAD with MCP Bridge
|
|
|
|
You have two options depending on your workflow:
|
|
|
|
#### Headless Mode (Command-line only)
|
|
|
|
Best for automated workflows, batch processing, or when you don't need visual feedback.
|
|
|
|
```bash
|
|
just freecad::run-headless
|
|
```
|
|
|
|
**Capabilities:** All modeling operations, export, scripting.
|
|
**Limitations:** No screenshots, no visual feedback, no color/visibility control.
|
|
|
|
#### GUI Mode (Full graphical interface)
|
|
|
|
Best for interactive design work where you want to see results visually.
|
|
|
|
```bash
|
|
just freecad::run-gui
|
|
```
|
|
|
|
**Capabilities:** Everything headless mode can do, plus screenshots, colors, view control.
|
|
|
|
### Verifying Connection
|
|
|
|
Once FreeCAD is running with the MCP bridge, you can verify the connection:
|
|
|
|
```text
|
|
"Check the FreeCAD connection status"
|
|
```
|
|
|
|
Claude will use the `get_connection_status` tool to confirm the bridge is working.
|
|
|
|
---
|
|
|
|
## Running Modes
|
|
|
|
### Headless vs GUI Mode
|
|
|
|
| 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 |
|
|
|
|
### Detecting the Current Mode
|
|
|
|
When working with Claude, it will automatically detect whether FreeCAD is in GUI or headless mode and adapt accordingly. GUI-only operations will return informative errors in headless mode rather than crashing.
|
|
|
|
---
|
|
|
|
## Basic Workflows
|
|
|
|
### Creating a Document
|
|
|
|
Every FreeCAD project needs a document. You can ask Claude:
|
|
|
|
```text
|
|
"Create a new FreeCAD document called 'MyProject'"
|
|
```
|
|
|
|
Claude will use the `create_document` tool.
|
|
|
|
### Creating Simple Shapes
|
|
|
|
Ask Claude to create primitive shapes:
|
|
|
|
```text
|
|
"Create a box that's 50mm long, 30mm wide, and 10mm tall"
|
|
"Add a cylinder with radius 5mm and height 20mm"
|
|
"Create a sphere with 15mm radius"
|
|
```
|
|
|
|
### Positioning Objects
|
|
|
|
Move and rotate objects:
|
|
|
|
```text
|
|
"Move the box to position (100, 50, 0)"
|
|
"Rotate the cylinder 45 degrees around the Z axis"
|
|
```
|
|
|
|
### Boolean Operations
|
|
|
|
Combine shapes:
|
|
|
|
```text
|
|
"Fuse the box and cylinder together"
|
|
"Cut a hole through the box using the cylinder"
|
|
"Find the intersection of the two shapes"
|
|
```
|
|
|
|
### Saving and Exporting
|
|
|
|
```text
|
|
"Save the document as MyProject.FCStd"
|
|
"Export the model to STEP format"
|
|
"Export for 3D printing as STL"
|
|
```
|
|
|
|
---
|
|
|
|
## Object Creation Examples
|
|
|
|
### Example 1: Simple Box with Hole
|
|
|
|
**Request:**
|
|
|
|
```text
|
|
Create a 50x50x20mm box with a 10mm diameter hole through the center.
|
|
```
|
|
|
|
**What Claude does:**
|
|
|
|
1. Creates a document
|
|
1. Creates a box (50x50x20)
|
|
1. Creates a cylinder (radius 5, height 30) positioned at center
|
|
1. Performs boolean cut operation
|
|
1. Returns the result
|
|
|
|
### Example 2: Pipe/Tube Shape
|
|
|
|
**Request:**
|
|
|
|
```text
|
|
Create a pipe with outer diameter 40mm, inner diameter 30mm, and length 100mm.
|
|
```
|
|
|
|
**What Claude does:**
|
|
|
|
1. Creates outer cylinder (radius 20, height 100)
|
|
1. Creates inner cylinder (radius 15, height 100)
|
|
1. Cuts inner from outer to create hollow tube
|
|
|
|
### Example 3: L-Bracket
|
|
|
|
**Request:**
|
|
|
|
```text
|
|
Create an L-shaped bracket:
|
|
- Horizontal part: 100mm x 50mm x 5mm
|
|
- Vertical part: 5mm x 50mm x 80mm standing on the horizontal part
|
|
```
|
|
|
|
**What Claude does:**
|
|
|
|
1. Creates horizontal box
|
|
1. Creates vertical box positioned at correct location
|
|
1. Fuses them together
|
|
|
|
---
|
|
|
|
## PartDesign Workflow
|
|
|
|
For parametric modeling that maintains design history, use the PartDesign workflow.
|
|
|
|
### Understanding PartDesign Concepts
|
|
|
|
**Body**: A container for a single solid model built from features.
|
|
|
|
**Sketch**: A 2D drawing that defines profiles for 3D operations.
|
|
|
|
**Features**: Operations like Pad (extrude), Pocket (cut), Fillet, etc.
|
|
|
|
### Basic PartDesign Example
|
|
|
|
**Request:**
|
|
|
|
```text
|
|
Create a parametric mounting plate:
|
|
1. Start with a PartDesign body
|
|
2. Create a sketch on the XY plane with a 100x60mm rectangle
|
|
3. Pad it 8mm thick
|
|
4. Add four 5mm holes near each corner for mounting screws
|
|
5. Fillet all edges with 2mm radius
|
|
```
|
|
|
|
**What Claude does:**
|
|
|
|
1. `create_partdesign_body()` - Creates the Body container
|
|
1. `create_sketch(body_name="Body", plane="XY_Plane")` - Creates attached sketch
|
|
1. `add_sketch_rectangle(...)` - Adds the profile geometry
|
|
1. `pad_sketch(sketch_name="Sketch", length=8)` - Extrudes to solid
|
|
1. Creates new sketches with points for hole locations
|
|
1. `create_hole(...)` for each mounting hole
|
|
1. `fillet_edges(...)` - Rounds the edges
|
|
|
|
### Revolving Profiles
|
|
|
|
**Request:**
|
|
|
|
```text
|
|
Create a turned part:
|
|
- Draw a profile on the XZ plane
|
|
- Revolve it 360 degrees around the X axis
|
|
```
|
|
|
|
**What Claude does:**
|
|
|
|
1. Creates body and sketch on XZ plane
|
|
1. Draws the profile using lines and arcs
|
|
1. Uses `revolution_sketch()` to create the solid
|
|
|
|
### Pattern Operations
|
|
|
|
**Request:**
|
|
|
|
```text
|
|
Create a plate with a row of 6 holes spaced 15mm apart.
|
|
```
|
|
|
|
**What Claude does:**
|
|
|
|
1. Creates the base plate
|
|
1. Creates one hole feature
|
|
1. Uses `linear_pattern()` to repeat the hole
|
|
|
|
---
|
|
|
|
## Complete Example: Mounting Bracket
|
|
|
|
This detailed example shows a complete workflow for creating a practical part.
|
|
|
|
### Design Requirements
|
|
|
|
Create a mounting bracket with:
|
|
|
|
- Base plate: 80mm x 60mm x 5mm
|
|
- Vertical support: 5mm thick, 50mm tall, 60mm wide
|
|
- Two mounting holes (6mm diameter) on the base
|
|
- One slot (10mm x 20mm) on the vertical support
|
|
- 3mm fillets on external corners
|
|
|
|
### Step-by-Step Workflow
|
|
|
|
#### Step 1: Ask Claude to create the bracket
|
|
|
|
```text
|
|
Create a mounting bracket with the following specifications:
|
|
|
|
Base plate:
|
|
- Size: 80mm x 60mm x 5mm
|
|
- Two 6mm diameter mounting holes, centered 15mm from each short edge
|
|
|
|
Vertical support:
|
|
- Attached to one end of the base
|
|
- 5mm thick, 60mm wide, 50mm tall
|
|
- One slot: 10mm wide x 20mm tall, centered
|
|
|
|
Finish:
|
|
- 3mm fillet on all outer edges
|
|
- Export as STEP file when done
|
|
```
|
|
|
|
#### Step 2: Claude's approach
|
|
|
|
Claude will break this down into manageable operations:
|
|
|
|
```python
|
|
# 1. Create document and PartDesign body
|
|
create_document(name="MountingBracket")
|
|
create_partdesign_body(name="Body")
|
|
|
|
# 2. Create base plate sketch and pad
|
|
create_sketch(body_name="Body", plane="XY_Plane", name="BaseSketch")
|
|
add_sketch_rectangle(sketch_name="BaseSketch", x=0, y=0, width=80, height=60)
|
|
pad_sketch(sketch_name="BaseSketch", length=5)
|
|
|
|
# 3. Add vertical support
|
|
create_sketch(body_name="Body", plane="XZ_Plane", name="SupportSketch")
|
|
# ... add geometry
|
|
pad_sketch(sketch_name="SupportSketch", length=60)
|
|
|
|
# 4. Add mounting holes
|
|
create_sketch(body_name="Body", plane="XY_Plane", name="HoleSketch")
|
|
add_sketch_point(sketch_name="HoleSketch", x=15, y=30)
|
|
add_sketch_point(sketch_name="HoleSketch", x=65, y=30)
|
|
create_hole(sketch_name="HoleSketch", diameter=6, hole_type="ThroughAll")
|
|
|
|
# 5. Add slot (as pocket)
|
|
create_sketch(body_name="Body", plane="Face...", name="SlotSketch")
|
|
add_sketch_rectangle(...)
|
|
pocket_sketch(sketch_name="SlotSketch", length=5, type="ThroughAll")
|
|
|
|
# 6. Add fillets
|
|
fillet_edges(object_name="...", radius=3)
|
|
|
|
# 7. Export
|
|
export_step(file_path="/path/to/bracket.step")
|
|
```
|
|
|
|
#### Step 3: View the result (GUI mode)
|
|
|
|
```text
|
|
Take a screenshot of the bracket from an isometric view
|
|
```
|
|
|
|
Claude will use `get_screenshot(view_angle="Isometric")` to capture and display the result.
|
|
|
|
---
|
|
|
|
## Tips and Best Practices
|
|
|
|
### 1. Be Specific with Dimensions
|
|
|
|
**Good:** "Create a box 50mm x 30mm x 10mm"
|
|
|
|
**Vague:** "Create a small box"
|
|
|
|
### 2. Specify Units
|
|
|
|
FreeCAD uses millimeters by default. Always include units to avoid confusion:
|
|
|
|
```text
|
|
"Create a cylinder with 25.4mm (1 inch) diameter"
|
|
```
|
|
|
|
### 3. Use Meaningful Names
|
|
|
|
```text
|
|
"Create a box named 'BasePlate' and a cylinder named 'MountingHole'"
|
|
```
|
|
|
|
This makes it easier to reference objects later.
|
|
|
|
### 4. Work Incrementally
|
|
|
|
For complex parts, build step by step:
|
|
|
|
1. Create the basic shape
|
|
1. Verify it looks correct
|
|
1. Add features one at a time
|
|
1. Check after each major operation
|
|
|
|
### 5. Save Frequently
|
|
|
|
```text
|
|
"Save the document"
|
|
```
|
|
|
|
FreeCAD can crash, and you don't want to lose work.
|
|
|
|
### 6. Use PartDesign for Parametric Parts
|
|
|
|
If you might need to modify dimensions later, use the PartDesign workflow with sketches rather than direct Part operations.
|
|
|
|
### 7. Export to Multiple Formats
|
|
|
|
For manufacturing or 3D printing:
|
|
|
|
```text
|
|
"Export as STEP for CNC machining and STL for 3D printing"
|
|
```
|
|
|
|
### 8. Use the execute_python Tool for Advanced Operations
|
|
|
|
For operations not covered by the standard tools, Claude can execute custom Python:
|
|
|
|
```text
|
|
"Calculate the volume and center of mass of the part"
|
|
```
|
|
|
|
Claude will use `execute_python()` to run the necessary FreeCAD Python commands.
|
|
|
|
### 9. Check GUI Mode for Visual Features
|
|
|
|
Before asking for screenshots or colors:
|
|
|
|
```text
|
|
"Is FreeCAD running in GUI mode?"
|
|
```
|
|
|
|
### 10. Use Patterns for Repetitive Features
|
|
|
|
Instead of creating many individual features:
|
|
|
|
```text
|
|
"Create one hole and pattern it in a 4x3 grid with 20mm spacing"
|
|
```
|
|
|
|
---
|
|
|
|
## Common Operations Quick Reference
|
|
|
|
| Task | How to Ask |
|
|
| ---------------- | ------------------------------------------------------- |
|
|
| Create box | "Create a box 50x30x10mm" |
|
|
| Create cylinder | "Create a cylinder with 10mm radius and 20mm height" |
|
|
| Move object | "Move MyBox to position (100, 50, 0)" |
|
|
| Rotate object | "Rotate MyCylinder 45 degrees around Z axis" |
|
|
| Boolean union | "Fuse Box and Cylinder together" |
|
|
| Boolean subtract | "Cut Cylinder from Box" |
|
|
| Create hole | "Add a 6mm through hole at (25, 15)" |
|
|
| Fillet edges | "Add 3mm fillet to all edges" |
|
|
| Chamfer edges | "Add 2mm chamfer to selected edges" |
|
|
| Export STEP | "Export to STEP format" |
|
|
| Export STL | "Export for 3D printing" |
|
|
| Save document | "Save the document as MyPart.FCStd" |
|
|
| Screenshot | "Take a screenshot from the front view" (GUI mode only) |
|
|
| Change color | "Make the box red" (GUI mode only) |
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### "GUI not available" Error
|
|
|
|
You're running in headless mode and trying to use a GUI-only feature. Either:
|
|
|
|
- Switch to GUI mode: `just freecad::run-gui`
|
|
- Use an alternative approach (e.g., skip visual operations)
|
|
|
|
### Objects Not Appearing
|
|
|
|
Make sure to recompute the document:
|
|
|
|
```text
|
|
"Recompute the document"
|
|
```
|
|
|
|
### Boolean Operations Failing
|
|
|
|
Ensure:
|
|
|
|
1. Both objects have valid shapes
|
|
1. The objects actually intersect
|
|
1. Objects are in the same document
|
|
|
|
### Sketch Errors
|
|
|
|
Sketches need to be fully constrained for PartDesign operations. Ask Claude to:
|
|
|
|
```text
|
|
"Check if the sketch is fully constrained"
|
|
```
|
|
|
|
### Connection Issues
|
|
|
|
If the MCP bridge isn't responding:
|
|
|
|
1. Check FreeCAD is running with the bridge started
|
|
1. Verify ports 9875 (XML-RPC) and 9876 (socket) are available
|
|
1. Restart FreeCAD with `just freecad::run-gui` or `just freecad::run-headless`
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- See [MCP_TOOLS_REFERENCE.md](MCP_TOOLS_REFERENCE.md) for detailed API documentation
|
|
- Explore the FreeCAD wiki for advanced techniques
|
|
- Practice with simple parts before attempting complex assemblies
|