freecad-robust-mcp-fc111/docs/USER_GUIDE.md

# 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 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