mcp-to-freecad protocol bridging with xml-rpc tunneling
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.
Unique: Uses FastMCP framework with a dedicated FreeCADConnection singleton to abstract XML-RPC complexity, enabling multiple AI frameworks to control FreeCAD through standardized MCP protocol without modifying FreeCAD's core codebase — the addon runs as a separate workbench with thread-safe QTimer-based task queuing
vs alternatives: Unlike direct FreeCAD Python API calls or REST wrappers, this approach maintains FreeCAD's GUI responsiveness by queuing operations through the Qt event loop while supporting multiple concurrent AI clients via MCP's standardized interface
parametric cad object creation with multi-workbench type support
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.
Unique: Abstracts FreeCAD's multi-workbench object model through a unified create_object interface that handles type-specific initialization, property serialization, and computed property calculation — enabling AI agents to reason about CAD objects without deep FreeCAD API knowledge
vs alternatives: More flexible than FreeCAD's native Python API for AI use because it returns serialized object state immediately and handles workbench-specific initialization transparently, whereas direct API calls require knowledge of each workbench's object hierarchy
automatic freecad connection management with singleton pattern and reconnection logic
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.
Unique: Uses a singleton pattern with automatic reconnection logic to abstract away XML-RPC connection complexity, allowing MCP tools to invoke FreeCAD operations without managing connection state — the connection is transparent to tool implementations
vs alternatives: More resilient than naive RPC clients because it implements exponential backoff and automatic reconnection; more efficient than creating new connections per request because it reuses a single persistent connection
object serialization with computed property calculation and type-aware json encoding
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.
Unique: Automatically calculates and includes computed properties (volume, mass, bounding box) in serialized objects, providing AI agents with derived metrics without requiring separate analysis steps — the RPC server handles all geometry calculations transparently
vs alternatives: More informative than raw property dumps because it includes computed metrics; more efficient than requiring separate analysis calls because properties are calculated once during serialization
live cad viewport screenshot capture with viewpoint control
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.
Unique: Bridges FreeCAD's native viewport rendering with MCP's JSON protocol by capturing and base64-encoding screenshots, allowing vision-capable AI models to inspect CAD geometry without requiring separate image file I/O or display server access
vs alternatives: Unlike file-based screenshot approaches, this returns images directly in MCP responses, enabling stateless AI workflows without filesystem dependencies; unlike headless rendering, it leverages FreeCAD's native GPU-accelerated viewport
arbitrary python code execution within freecad's runtime context
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.
Unique: Provides direct Python code execution within FreeCAD's runtime via MCP, allowing AI agents to leverage FreeCAD's full Python API without being constrained to predefined tool schemas — trades safety for flexibility and expressiveness
vs alternatives: More powerful than tool-based approaches because it enables one-shot execution of complex workflows, but less safe than sandboxed execution environments; positioned for trusted, internal AI automation rather than public-facing services
document and object state inspection with hierarchical querying
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.
Unique: Serializes FreeCAD's internal object graph to JSON with computed properties included, enabling AI agents to reason about CAD state without parsing binary FreeCAD files or maintaining separate state tracking — the RPC server handles all serialization complexity
vs alternatives: More accessible than direct FreeCAD Python API introspection because it returns structured JSON; more complete than file-based approaches because it includes computed/derived properties and real-time state
object property mutation with type-aware validation
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.
Unique: Provides direct property mutation through MCP without requiring knowledge of FreeCAD's property editor UI or Python API details — the RPC server handles type coercion and attribute setting transparently
vs alternatives: Simpler than FreeCAD's native Python API for AI use because it accepts flat JSON property dictionaries; more flexible than GUI-based editing because it enables programmatic batch updates
+4 more capabilities