feat: Initial commit of FreeCAD MCP/tooling proj.
This commit is contained in:
Sean P. Kane
@@ -0,0 +1,485 @@
|
||||
# FreeCAD 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 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 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 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 run-gui` or `just 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
|
||||
Reference in New Issue
Block a user