Connects to a running FreeCAD 1.0/1.1+ instance to inspect and tutor within the user's live model: lists documents and object graphs, diagnoses sketches (degrees of freedom, missing/conflicting constraints), analyzes shapes, finds edges/faces, measures distances, explains errors, and captures viewport or full-window screenshots. Also provides UI guidance (menu paths, toolbar/shortcut lookup, on-screen highlighting of buttons and panels, camera/view control) and permission-gated, undo-wrapped editing tools for Sketcher, PartDesign (pad, pocket, revolution, loft, sweep, patterns, holes, thickness), Part booleans/fillets/chamfers, TechDraw pages and dimensions, property/variable-set editing, and export to STEP, STL, OBJ, 3MF, PDF, and SVG.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@FreeCAD Tutor MCP Where is the Pad button, and why is it greyed out right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This is a completely vibe-coded MCP server to help my brother learn FreeCAD with Claude as an interactive tutor. Pretty much everything else below this sentence is AI-generated.
FreeCAD Tutor MCP connects FreeCAD 1.0 / 1.1+ to Claude Desktop on Windows so you can ask Claude for help while you model.
With it connected, Claude can:
Show you where buttons are — highlight toolbar buttons, menus, or panels right on your FreeCAD screen instead of making you hunt for them.
Explain why something broke — look at your sketch, shape, open dialog, and error messages, then translate them into plain English.
Demonstrate safely — if you ask Claude to show you how a feature works, it asks before changing anything, puts demos in a separate practice file (Tutor_Demo), and every step can be undone with Ctrl+Z.
Make sure you already have these installed on your Windows 10 or Windows 11 PC:
FreeCAD 1.0 or 1.1+ (freecad.org)
Claude Desktop (claude.ai/download)
You do not need Git, Python, or a GitHub account.
Related MCP server: FreeCAD MCP
Download the project ZIP file here: 👉 Download FreeCAD Tutor MCP (.zip) (Or click the green Code button above, then Download ZIP.)
Find the downloaded .zip file in your Downloads folder.
Right-click it → click Extract All... → extract it somewhere easy to find (like Documents).
Open the extracted folder (freecad-tutor-mcp-main).
Double-click install.bat.
Wait for the black window to finish. It handles everything automatically:
Installs the FreeCADTutorMCP add-on into your FreeCAD Mod folder.
Sets up a local Python environment inside this folder (and downloads uv / Python automatically if your PC doesn't have them).
Backs up and updates your Claude Desktop config file (%APPDATA%\Claude\claude_desktop_config.json).
Open (or restart) FreeCAD. The bridge starts quietly in the background on your PC (127.0.0.1:9876).
Restart Claude Desktop (if it was already open, close it from the system tray and reopen it).
In Claude Desktop, create a new Project (for example, FreeCAD Course).
Open CLAUDE_PROJECT_INSTRUCTIONS.md, copy all of its text, and paste it into the project's Instructions.
This tells Claude to act like a patient tutor—explaining why things work and letting you click the buttons yourself—instead of taking over your model.
Once both apps are open, try asking questions like:
"Where is the Pad button, and why is it greyed out right now?"
"Why won't my sketch turn green?"
"Look at what I selected and tell me why my fillet failed."
"Open a practice file and show me how Revolve works step by step."
Nothing leaves your PC except the text and screenshots sent to Claude in your chat.
Read first, ask before editing: Claude can inspect your model and take screenshots freely, while any action that changes your model prompts you for permission first.
Full Undo: Every model change is wrapped in a FreeCAD undo step (Ctrl+Z).
Local lock: FreeCAD generates a private token on your own PC (%APPDATA%\FreeCAD\mcp_auth_token) so other programs cannot connect without permission.
Connection & History: get_rpc_status, get_console_output, get_recent_activity, explain_freecad_error, get_undo_redo_status
Documents & Objects: list_documents, get_document_graph (with active Body.Tip, open Task panel controls, and plain-English error explanations), inspect_object, tracked_recompute
Shapes & Sketches: analyze_shape (including optional deep BOPCheck), find_edges, find_faces, measure_distance, get_sketch_diagnostics (DoF, FullyConstrained, open vertices, missing/conflicting/redundant constraints)
find_ui_command — Menu path, toolbar, shortcut, and why a button is disabled
highlight_ui_element — On-screen spotlight box + callout label in FreeCAD
list_workbenches / get_selection
set_view — Standard views (Isometric, Top, Front, Right, etc.) and zoom to selection
get_view — Capture the 3D viewport or the full FreeCAD window (including Task panels and dialogs)
Ctrl+Z undoable)Files: create_document (defaults to Tutor_Demo), save_document, open_document, close_document (refuses to discard unsaved work unless told), export_document (STEP, STL, OBJ, 3MF)
UI & Undo: activate_workbench, set_selection, undo, redo
Sketcher: create_sketch, edit_sketch (auto_constrain, lines, polylines, rectangles, circles, arcs, slots, polygons, fillets, construction geometry, external geometry, constraint editing/deletion)
PartDesign: create_partdesign_body, pad_sketch, pocket_sketch, partdesign_thickness, partdesign_hole, partdesign_revolution, partdesign_groove, partdesign_loft, partdesign_sweep, partdesign_mirrored, partdesign_linear_pattern, partdesign_polar_pattern, partdesign_draft, create_datum_plane
Parameters & Appearance: create_varset, set_property (dimensions and formula expressions), set_appearance (visibility, transparency, color)
Part (CSG): create_part_primitive, boolean_operation (Fuse, Cut, Common), fillet_edges, chamfer_edges
TechDraw (2D Drawings): create_techdraw_page, add_techdraw_view, add_techdraw_dimension, add_techdraw_section, export_techdraw_page (PDF / SVG)
Escape Hatch: execute_script (undo-transaction-wrapped Python)
If you prefer PowerShell over install.bat:
git clone https://github.com/alex-r-t/freecad-tutor-mcp.git
cd freecad-tutor-mcp
.\install.ps1Run the unit & mocked test suite:
uv run pytest -vRun live FreeCAD verification (requires FreeCAD 1.0/1.1+ installed):
freecadcmd.exe -c "import sys; sys.argv=['live_smoke.py','--headless']; exec(open('tests/live_smoke.py').read(), {'__name__':'__main__'})"
uv run python tests/live_smoke.py --guiFreeCAD Tutor MCP was built from scratch for student tutoring by combining architectural ideas, safety patterns, and FreeCAD API lessons from several open-source FreeCAD MCP projects and FreeCAD itself:
theosib/FreeCAD-MCP-Server (Timothy Miller, LGPL-2.1-or-later) — Inspired the dual-process TCP JSON-RPC 2.0 addon/bridge architecture (127.0.0.1:9876, newline-delimited framing), workbench loader pattern, and deep runtime diagnostic tools (list_documents, get_document_graph, inspect_object, analyze_shape, get_sketch_diagnostics, tracked_recompute, execute_script).
neka-nat/freecad-mcp (Shirokuma / k tanaka, MIT) — Inspired the hardened Qt main-thread GUI dispatcher (rpc_server.py: per-call response queues, QueuedConnection wakeups, bounded drag deferral) and the crash-safe Gui.activeView() / saveImage viewport guard (get_view TechDraw-tab safety).
spkane/freecad-addon-robust-mcp-server (Sean P. Kane and contributors, Apache-2.0 AND MIT) — Inspired GUI context and safety tooling (get_selection / set_selection, list_workbenches / activate_workbench, Report view QTextEdit capture in get_console_output, undo / redo transaction wrappers), FreeCAD 1.x AttachmentSupport compatibility handling, and local token authentication for the bridge.
sergiudanstan/freecad-mcp (Dan Stan, MIT) — Inspired TechDraw 2D drawing and template patterns (create_techdraw_page, add_techdraw_view, add_techdraw_dimension, add_techdraw_section, export_techdraw_page) and broad Part / PartDesign / Sketcher tool coverage.
FreeCAD/FreeCAD (LGPL-2.1-or-later) — Upstream FreeCAD 1.1 source tree referenced for Python/C++ APIs (SketchObjectPyImp.cpp, DocumentObjectPyImp.cpp, FeaturePad.cpp, FeaturePocket.cpp, PartDesign::Plane, App::VarSet, and TechDrawGui).
Other FreeCAD MCP ecosystem repositories surveyed during initial architecture research:
bonninr/freecad_mcp (Rodolfo Bonnin, MIT)
See NOTICE for detailed component-level attributions.
FreeCAD Tutor MCP is distributed under LGPL-2.1-or-later. See LICENSE and NOTICE.
Switch FreeCAD's active workbench (e.g., 'PartDesignWorkbench', 'PartWorkbench', 'TechDrawWorkbench').
Inputs: name (required). Returns: object
Add a 2D TechDraw dimension (Distance, Radius, Diameter, Angle) referencing view edges/vertices (undoable).
Inputs: page_name (required), view_name (required), references (required), x, +5 more. Returns: object
Add a TechDraw cross-section view (DrawViewSection) cutting through a BaseView (undoable).
Inputs: page_name (required), base_view_name (required), x, y, +6 more. Returns: object
Add an orthographic view or multi-view Projection Group to a TechDraw page (undoable).
Inputs: page_name (required), object_name (required), scale, views, +3 more. Returns: object
Inspect face/edge topology, bounding box, volume, and validity (optional OCC BOPCheck).
Args:
name: Object name in the document.
deep_check: Set True to run OCC's slower deep Shape.check(True) BOP validity test.
doc_name: Target document name (empty string uses ActiveDocument).
Inputs: name (required), doc_name, deep_check. Returns: object
Run a Part CSG Boolean ('Fuse', 'Cut', or 'Common') between two objects (undoable).
Inputs: base_name (required), operation (required), tool_name (required), name, +1 more. Returns: object
Bevel selected edges (e.g. ['Edge1']) on a feature or shape (undoable).
Inputs: edges (required), object_name (required), name, size, +1 more. Returns: object
Close a document safely (refuses if modified unless save_before_close or discard_unsaved is True).
Inputs: doc_name, discard_unsaved, save_before_close. Returns: object
Create a PartDesign::Plane Datum Plane inside a Body (TNP-safe sketch plane) (undoable).
Inputs: body_name (required), name, offset, doc_name, +4 more. Returns: object
Create a new FreeCAD document (defaults to a safe 'Tutor_Demo' scratch file for demonstrations).
Inputs: name, activate. Returns: object
Create a PartDesign::Body container (undoable).
Inputs: name, doc_name. Returns: object
Create a Part CSG primitive ('Box', 'Cylinder', 'Sphere', or 'Cone') (undoable).
Inputs: shape_type (required), name, doc_name, position, +1 more. Returns: object
Create a Sketcher::SketchObject on an Origin plane or face (undoable).
Inputs: name, plane, doc_name, body_name. Returns: object
Create a TechDraw 2D drawing sheet with an SVG template (undoable).
Inputs: name, doc_name, template. Returns: object
Create a FreeCAD 1.0/1.1 App::VarSet parametric variable table (undoable).
Inputs: name, doc_name, variables. Returns: object
Add/edit/delete Sketch geometry & constraints with automatic Coincident/H/V constraining (undoable).
Inputs: sketch_name (required), doc_name, geometries, constraints, +7 more. Returns: object
Execute Python inside FreeCAD's main thread (escape hatch; undoable when wrap_transaction=True).
Inputs: script (required), doc_name, wrap_transaction. Returns: object
Translate a cryptic FreeCAD/OpenCASCADE error message into beginner causes and fixes.
Inputs: error_message (required). Returns: object
Export Bodies or solids to .step/.stp, .stl, .obj, .3mf, .iges, or .brep.
Inputs: path (required), doc_name, object_names, export_format. Returns: object
Export a TechDraw drawing page to PDF or SVG.
Inputs: path (required), page_name (required), doc_name, export_format. Returns: object
Round selected edges (e.g. ['Edge1', 'Edge2']) on a feature or shape (undoable).
Inputs: edges (required), object_name (required), name, radius, +1 more. Returns: object
Find EdgeN names on a shape matching direction ('X'/'Y'/'Z'/'+Z'/'-Z'), length, or location.
Inputs: object_name (required), length, doc_name, direction, +6 more. Returns: object
Find FaceN names on a shape matching normal ('+Z', '-Z', 'X'), area, surface type, or point.
Inputs: object_name (required), area, normal, doc_name, +6 more. Returns: object
Search live FreeCAD commands for menu paths, toolbars, shortcuts, and why a button is greyed out.
Args: query: Keyword such as 'Pad', 'Fillet', 'Sketch', or 'TechDraw'. workbench_filter: Optional command prefix filter (e.g. 'PartDesign', 'Sketcher'). limit: Max results (1-50).
Inputs: query (required), limit, workbench_filter. Returns: object
Read recent lines from FreeCAD's Report view / console log (1-1000 lines).
Inputs: lines. Returns: object
Inspect the feature tree, dependencies, error messages, UI edit state, and TNP warnings.
Args: doc_name: Document name; empty string uses the active document. include_properties: Keep False (default) for a compact graph; set True for all properties.
Inputs: doc_name, include_properties. Returns: object
Read recent student/model events recorded by the FreeCAD observer (edits, undos, dialogs).
Inputs: limit, doc_name. Returns: object
Check connection health, addon protocol version, FreeCAD PID, and dispatch status.
Inputs: no named parameters. Returns: object
Get objects and sub-elements (Face1, Edge2, etc.) currently selected by the user in FreeCAD.
Inputs: no named parameters. Returns: object
Inspect Sketch DoF, OpenVertices, missing/conflicting/redundant constraints, and tutor hints.
Inputs: name (required), doc_name. Returns: object
Check available undo/redo steps and transaction names.
Inputs: doc_name. Returns: object
Capture the 3D viewport (capture_scope='viewport') or full FreeCAD window ('window') as PNG.
Args: view_name: 'Current', 'Isometric', 'Front', 'Top', 'Right', 'Back', 'Left', 'Bottom', 'Dimetric', or 'Trimetric'. width: Optional explicit image width (auto-scaled <=1024px viewport / <=1280px window). height: Optional explicit image height. focus_object: Optional object name to zoom/fit before capturing. capture_scope: 'viewport' for clean 3D render, or 'window' to include Task panels, Combo View, and dialogs.
Inputs: width, height, view_name, focus_object, +1 more. Returns: result
Put a temporary, click-through visual spotlight on a FreeCAD button, menu, panel, or workbench selector.
Args: target: Command name (e.g. 'PartDesign_Pad'), button label ('Pad'), or panel name ('Model', 'Tasks', 'Report view', 'Workbench'). label: Optional short callout text shown next to the highlight frame. duration_s: Auto-dismiss time in seconds (1.0-20.0). clear: Set True to immediately remove any active highlight.
Inputs: clear, label, target, duration_s. Returns: object
Dump all properties, validity state, error description, and shape metadata for one object.
Inputs: name (required), doc_name. Returns: object
List all open FreeCAD documents (active_document, count, and documents list).
Inputs: no named parameters. Returns: object
List all FreeCAD workbenches and show which one is currently active.
Inputs: no named parameters. Returns: object
Measure minimum 3D distance and delta vector between two objects or Face/Edge/Vertex refs.
Inputs: object1 (required), object2, doc_name, subelement1, +1 more. Returns: object
Open a .FCStd file (or import a .step/.stp/.iges/.igs file into a new document).
Inputs: path (required), activate. Returns: object
Extrude a Sketch inside a PartDesign Body using Pad (undoable; rolls back if invalid).
Inputs: sketch_name (required), name, length, doc_name, +2 more. Returns: object
Taper selected solid faces by a draft angle (PartDesign::Draft) (undoable).
Inputs: faces (required), object_name (required), name, angle, +4 more. Returns: object
Revolve a Sketch around an axis to subtract/cut material in PartDesign (undoable).
Inputs: sketch_name (required), axis, name, angle, +3 more. Returns: object
Drill parametric simple, counterbore, countersink, or threaded holes from a Sketch (undoable).
Inputs: sketch_name (required), name, depth, diameter, +7 more. Returns: object
Repeat PartDesign feature(s) along a line (PartDesign::LinearPattern) (undoable).
Inputs: feature_names (required), name, length, doc_name, +3 more. Returns: object
Loft between two or more Sketches (AdditiveLoft or SubtractiveLoft) (undoable).
Inputs: profile_names (required), name, ruled, closed, +2 more. Returns: object
Mirror PartDesign feature(s) across a plane (PartDesign::Mirrored) (undoable).
Inputs: feature_names (required), name, doc_name, mirror_plane. Returns: object
Repeat PartDesign feature(s) around an axis (PartDesign::PolarPattern) (undoable).
Inputs: feature_names (required), axis, name, angle, +3 more. Returns: object
Revolve a Sketch around an axis to add solid material in PartDesign (undoable).
Inputs: sketch_name (required), axis, name, angle, +3 more. Returns: object
Sweep a profile Sketch along a spine path (AdditivePipe or SubtractivePipe) (undoable).
Inputs: spine_name (required), profile_name (required), name, doc_name, +3 more. Returns: object
Hollow out a PartDesign solid by opening selected faces and setting wall thickness (undoable).
Inputs: faces (required), object_name (required), join, mode, +4 more. Returns: object
Cut material from a PartDesign Body using Pocket (undoable; rolls back if invalid).
Inputs: sketch_name (required), name, length, doc_name, +2 more. Returns: object
Redo the most recently undone FreeCAD transaction.
Inputs: doc_name. Returns: object
Save an open document to its existing .FCStd path or a new destination path.
Inputs: path, doc_name. Returns: object
Set object Visibility, Transparency (0-100), or ShapeColor [r, g, b] in the View tab (undoable).
Inputs: object_name (required), color, visible, doc_name, +1 more. Returns: object
Update a Data-tab property (Pad.Length, Fillet.Radius, VarSet fields) or bind an expression (undoable).
Inputs: object_name (required), property_name (required), group, value, +4 more. Returns: object
Highlight/select objects or sub-elements (e.g. ['Pad', 'Pad.Face1']) in FreeCAD's viewport.
Inputs: names (required), doc_name, clear_first. Returns: object
Orient and zoom the 3D camera (Isometric, Front, Top, Right, Back/Rear, Left, Bottom) without screenshot.
Inputs: fit_all, view_name, focus_object, zoom_to_selection. Returns: object
Recompute the document and report new, resolved, and persistent object errors.
Inputs: doc_name. Returns: object
Undo the most recent FreeCAD transaction.
Inputs: doc_name. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 58 tools
Most tools target clearly distinct CAD actions or resources, especially across document, sketch, PartDesign, TechDraw, and UI-guidance domains. There is some potential confusion among diagnostic tools like get_document_graph, inspect_object, analyze_shape, and get_sketch_diagnostics, but their descriptions define different scopes.
The set is predominantly snake_case and mostly follows a verb_noun pattern such as create_sketch, list_documents, and export_document. Deviations like partdesign_thickness, boolean_operation, and tracked_recompute are readable but keep it from being fully uniform.
At 58 tools, the surface is far beyond the typical 3-15 range and almost certainly overwhelms an agent choosing among many partially adjacent operations. Even for a complex CAD application, the tool set is excessively large and would benefit from consolidation or higher-level composite tools.
Coverage is broad: document lifecycle, sketching, PartDesign features, Part primitives/booleans, TechDraw, exports, diagnostics, undo/redo, and UI tutoring are all represented. Notable gaps remain, such as an explicit delete-object/delete-feature tool and broader assembly or datum-line/point coverage.
CAD in ChatGPT and Claude: editable parts, STEP/STL/drawings, in-chat 3D, automatic checks.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Your own computer's files from ChatGPT or Claude: folder rules, confirmations and undo.
