freecad-mcp

Implements a three-tier architecture that translates Model Context Protocol (MCP) tool calls from AI clients into XML-RPC method invocations against a FreeCAD addon server running on localhost:9875. The FastMCP framework exposes FreeCAD operations as standardized MCP tools, while a singleton FreeCADConnection class manages the XML-RPC client connection with automatic reconnection and error handling. This decouples AI frameworks (Claude Desktop, LangChain, Google ADK) from FreeCAD's GUI thread, enabling safe asynchronous control.

Exposes a create_object MCP tool that instantiates FreeCAD objects across multiple workbenches (Part, PartDesign, Draft, Sketcher, Assembly, etc.) by accepting a type string and property dictionary. The RPC server's object creation logic maps type names to FreeCAD class constructors, sets properties via setattr, and returns serialized object metadata including UUID, label, and computed properties. Supports complex objects like PartDesign::Body with nested features and Draft objects with geometric constraints.

Implements a FreeCADConnection singleton class that manages the XML-RPC client connection to the FreeCAD addon server. The singleton maintains a persistent connection, automatically reconnects on failure with exponential backoff, and provides a unified interface for all RPC calls. Connection state is cached to avoid repeated connection attempts. The MCP server instantiates this singleton once and reuses it for all tool invocations, ensuring connection pooling and efficient resource usage.

Implements object serialization logic in the RPC server that converts FreeCAD objects to JSON-compatible dictionaries. The serializer traverses object attributes, computes derived properties (e.g., bounding box, volume, mass), handles special types (lists, nested objects, geometry data), and encodes them as JSON. Computed properties are calculated on-demand and cached per object. The serializer handles type coercion for non-JSON types (e.g., converting vectors to tuples, colors to hex strings). Enables AI agents to reason about object state without understanding FreeCAD's internal object model.

Implements a get_view MCP tool that captures PNG screenshots of the FreeCAD 3D viewport from specified viewpoints (Isometric, Front, Top, Bottom, Left, Right, etc.) by invoking FreeCAD's camera positioning API and rendering the scene. Screenshots are base64-encoded and returned in the MCP response, enabling AI agents to receive visual feedback on model state without opening the FreeCAD GUI. The RPC server handles viewport rendering synchronously within the Qt event loop.

Exposes an execute_code MCP tool that accepts arbitrary Python code strings and executes them within FreeCAD's Python interpreter, with access to the FreeCAD API (App, Gui modules) and the current document. Code execution happens synchronously in the RPC server's thread, with stdout/stderr captured and returned in the response. This enables AI agents to perform complex operations not exposed by dedicated MCP tools, such as custom geometry calculations, macro-like workflows, or debugging.

Implements get_objects and get_object MCP tools that query FreeCAD document structure and return serialized object metadata including properties, computed values, and hierarchical relationships. The RPC server traverses the document's object tree, serializes each object's attributes to JSON, and handles special cases like sketches with geometry data and assemblies with part references. Enables AI agents to understand current CAD state without visual inspection.

Exposes an edit_object MCP tool that modifies properties of existing FreeCAD objects by accepting an object ID and property dictionary, then using Python's setattr to apply changes. The RPC server validates property types against the object's class definition and returns updated object metadata. Supports both simple properties (dimensions, colors) and complex properties (lists, nested objects). Changes are immediately reflected in the FreeCAD document.

Implements a delete_object MCP tool that removes objects from the FreeCAD document by ID. The RPC server invokes FreeCAD's object removal API, which handles cascading deletion of dependent features (e.g., removing a sketch deletes constraints and geometry). Returns success/failure status and updated document state. Enables AI agents to clean up intermediate objects or reset design iterations.

Exposes create_document and list_documents MCP tools that manage FreeCAD document lifecycle. create_document instantiates a new FreeCAD document with optional name and returns its ID; list_documents enumerates all open documents with metadata. The RPC server maintains document references and handles FreeCAD's document manager API. Enables AI agents to organize work across multiple design files.

Implements insert_part_from_library and get_parts_list MCP tools that provide access to FreeCAD's parts library (or custom libraries). get_parts_list enumerates available parts with metadata (name, category, description, thumbnail); insert_part_from_library instantiates a part into the current document by name or ID. The RPC server queries the library index and handles part instantiation, returning the created object's metadata. Enables AI agents to compose designs from pre-built components.

Implements a thread-safe request queue (rpc_request_queue) in the FreeCAD addon that serializes all RPC operations through FreeCAD's Qt event loop via QTimer callbacks. The RPC server runs in a separate thread from FreeCAD's GUI, so all operations that touch the document or viewport are queued and processed synchronously by the Qt main thread via process_gui_tasks() callback. This prevents race conditions and GUI crashes from concurrent access. The queue uses Python's thread-safe Queue class and processes tasks in FIFO order.