freecad-robust-mcp-fc111/docs/getting-started/quickstart.md

Quick Start

Get up and running with AI-assisted FreeCAD modeling in minutes.

---

Prerequisites

Before starting, ensure you have:

1. FreeCAD installed with the Robust MCP Bridge workbench
2. The MCP server installed (pip install freecad-robust-mcp)
3. Your MCP client configured (see Configuration)

---

Step 1: Start FreeCAD with the MCP Bridge

Option A: GUI Mode (Recommended for getting started)

1. Open FreeCAD
2. Switch to the Robust MCP Bridge workbench
3. Click Start Bridge in the toolbar
4. You should see: "MCP Bridge started! XML-RPC: localhost:9875, Socket: localhost:9876"

Option B: Headless Mode (For automation)

# If installed via Addon Manager (Linux)
FreeCADCmd ~/.local/share/FreeCAD/Mod/FreecadRobustMCPBridge/freecad_mcp_bridge/blocking_bridge.py

# If working from source
just freecad::run-headless

---

Step 2: Connect Your AI Assistant

With FreeCAD and the MCP server configured, open your AI assistant (Claude Code, Cursor, etc.) and verify the connection:

"Check the FreeCAD connection status"

The AI should respond with information about the connection mode, FreeCAD version, and whether GUI is available.

---

Step 3: Create Your First Model

Try these example prompts with your AI assistant:

Simple Box

"Create a new FreeCAD document and add a box that is 20mm x 10mm x 5mm"

Parametric Part with Fillet

"Create a parametric bracket:
1. Start with a 50x30mm rectangular sketch
2. Extrude it 10mm
3. Add a 3mm fillet to all edges"

Export for 3D Printing

"Export the current model to STL format for 3D printing"

---

Step 4: Explore Available Tools

The MCP server provides 82+ tools organized into categories:

Category	Examples
Primitives	create_box, create_cylinder, create_sphere
PartDesign	create_sketch, pad_sketch, pocket_sketch
Operations	boolean_operation, fillet_edges, chamfer_edges
Export	export_stl, export_step, export_3mf
View (GUI)	get_screenshot, set_object_color

See the Tools Reference for the complete list.

---

Example Workflows

Create a Mounting Bracket

"Help me create a mounting bracket with:
- 60x40mm base plate, 5mm thick
- Two mounting holes (5mm diameter) at the corners
- A vertical wall 30mm tall on one edge
- 2mm fillets on all external edges"

Modify an Existing Model

"Open my_part.FCStd and:
1. List all the objects in the document
2. Change the height of the Pad feature from 10mm to 15mm
3. Save the document"

Debug a Macro

"Read the macro 'MyMacro' and explain what it does.
Then run it and show me any errors."

---

Tips for Effective AI-Assisted Modeling

1. Be specific about dimensions - Include units (mm, cm, inches) in your requests
2. Use parametric approaches - Ask for PartDesign workflows instead of direct Part operations for parts you'll modify
3. Check console output - If something goes wrong, ask the AI to check the FreeCAD console for errors
4. Take screenshots - In GUI mode, ask for screenshots to verify the model looks correct
5. Save frequently - Ask the AI to save your document after significant changes

---

Next Steps

• Tools Reference - Complete API reference for all tools
• User Guide - Detailed workflows and best practices
• Connection Modes - Understanding connection modes