Skip to content

FreeCAD Robust MCP Server Comparison Analysis

This document analyzes existing FreeCAD Robust MCP server implementations to identify best practices and improvements for our architecture.

Existing Implementations

1. neka-nat/freecad-mcp (380+ stars)

Architecture:

  • XML-RPC server running inside FreeCAD (port 9875)
  • Queue-based GUI communication for thread safety
  • FastMCP-based MCP server connecting via XML-RPC

Key Features:

  • create_object() supports Part::, Draft::, PartDesign::, Fem:: types
  • get_view() captures screenshots with multiple perspectives
  • insert_part_from_library() for part library access
  • Smart screenshot handling (detects unsupported views like TechDraw)

Strengths:

  • Thread-safe queue system for GUI operations
  • Comprehensive object type support
  • Screenshot capabilities with view selection
  • Parts library integration

Weaknesses:

  • XML-RPC only (no embedded/headless mode)
  • No macro development tools
  • Limited debugging capabilities

2. jango-blockchained/mcp-freecad

Architecture:

  • 6 connection modes: Launcher, Server, Bridge, RPC, Wrapper, Mock
  • FastMCP 2.13.0+ with FastAPI integration
  • Multi-provider AI support (Claude, OpenAI, Google, OpenRouter)

Key Features:

  • AppImage/AppRun launcher integration
  • Connection recovery mechanisms
  • Resource caching and performance diagnostics
  • Modern GUI addon with real-time diagnostics

Strengths:

  • Most flexible connection options
  • Multi-AI provider support
  • Performance monitoring
  • Connection recovery/resilience

Weaknesses:

  • Complex setup with many moving parts
  • Heavier dependency footprint

3. contextform/freecad-mcp

Architecture:

  • Node.js-based MCP bridge (working_bridge.py)
  • AICopilot workbench integrated into FreeCAD
  • Cross-platform installer (freecad-mcp-setup)

Key Features:

  • 13 PartDesign operations (Pad, Revolution, Fillet, Chamfer, etc.)
  • 18 Part operations (Primitives, Booleans, Transforms)
  • 14 View control tools
  • Automated installer with OS detection

Strengths:

  • Most comprehensive CAD operation coverage
  • Excellent PartDesign/Part workbench integration
  • Easy installation process
  • Demo showcasing full workflow (house modeling)

Weaknesses:

  • Node.js dependency adds complexity
  • Less focus on debugging/development workflows

4. ATOI-Ming/FreeCAD-MCP

Architecture:

  • Server-client with stdio/TCP (port 9876)
  • GUI control panel inside FreeCAD
  • Macro-centric workflow

Key Features:

  • Macro templates (default, basic, part, sketch)
  • Automatic import injection in macros
  • Macro validation before execution
  • View control (front, top, right, axonometric)
  • Log management and report browser

Strengths:

  • Focus on macro development workflow
  • GUI panel for easy control
  • Automatic boilerplate injection
  • Comprehensive logging

Weaknesses:

  • Macro-only focus (no direct object creation)
  • Windows-centric paths in documentation

5. bonninr/freecad_mcp

Architecture:

  • Simple socket-based server
  • Two primary tools: get_scene_info and run_script

Key Features:

  • Comprehensive scene information retrieval
  • Arbitrary Python code execution
  • Minimal, focused API

Strengths:

  • Simple, easy to understand
  • Full Python access via run_script
  • Lightweight

Weaknesses:

  • Very minimal tool set
  • No specialized CAD operations

Feature Comparison Matrix

Feature neka-nat jango contextform ATOI-Ming bonninr Ours
Headless mode No Yes No No No Yes
GUI mode Yes Yes Yes Yes Yes Yes
XML-RPC Yes Yes No No No Yes
Socket/TCP No Yes No Yes Yes Yes
Embedded Python No No No No No Yes
Screenshot capture Yes Yes Yes No No Yes
Parts library Yes No No No No Yes
Macro support No No No Yes No Yes
PartDesign tools Basic Yes Yes Via macro No Yes
Boolean operations Yes Yes Yes Via macro No Yes
FEM support Yes No No No No Yes
Multi-AI provider No Yes No No No No
Connection recovery No Yes No No No Yes
Thread-safe GUI ops Yes Yes Unknown Unknown Unknown Yes
MCP Resources No No No No No Yes
MCP Prompts No No No No No Yes

Key Learnings & Improvements for Our Architecture

1. Communication Protocol

Learning: neka-nat uses XML-RPC which is proven and reliable.

Improvement: Support both XML-RPC (for compatibility) and JSON-RPC over sockets (simpler, more modern). Add embedded mode for true headless operation.

2. Thread-Safe GUI Operations

Learning: neka-nat's queue-based system is essential for GUI stability.

Improvement: Implement similar queue system with Qt timer for main thread execution:

# Queue-based GUI communication
rpc_request_queue = queue.Queue()
rpc_response_queue = queue.Queue()

def process_gui_tasks():
    """Execute queued operations on main GUI thread."""
    while not rpc_request_queue.empty():
        task = rpc_request_queue.get()
        result = task()
        rpc_response_queue.put(result)

3. Screenshot Capabilities

Learning: neka-nat handles unsupported view types gracefully.

Improvement: Add comprehensive view support with intelligent fallbacks:

  • Multiple view angles (Isometric, Front, Top, Right, etc.)
  • View type detection (skip TechDraw, Spreadsheet)
  • Configurable resolution and format

4. Macro Development Focus

Learning: ATOI-Ming's macro-centric approach is unique and valuable.

Improvement: Add dedicated macro tools:

  • create_macro with templates
  • validate_macro for syntax checking
  • run_macro with parameter passing
  • Automatic import injection

5. PartDesign Integration

Learning: contextform has the most comprehensive PartDesign coverage.

Improvement: Add specialized PartDesign tools:

  • Pad, Pocket, Revolution, Groove
  • Fillet, Chamfer
  • Hole (with standards support)
  • LinearPattern, PolarPattern
  • Mirrored

6. Connection Resilience

Learning: jango-blockchained has connection recovery mechanisms.

Improvement: Add connection health monitoring and auto-reconnect:

async def maintain_connection(self):
    """Background task to maintain connection health."""
    while self._running:
        if not await self.is_connected():
            await self.reconnect()
        await asyncio.sleep(5)

7. Parts Library Integration

Learning: neka-nat provides access to FreeCAD parts library.

Improvement: Expose parts library with search and filtering.

8. Comprehensive Logging

Learning: ATOI-Ming has excellent logging with GUI browser.

Improvement: Add structured logging with levels, rotation, and optional GUI viewer in plugin.

Updated Architecture Decisions

Based on this analysis, our architecture will:

  1. Support 3 connection modes:

  2. Embedded (headless, in-process FreeCAD)

  3. XML-RPC (proven, compatible with neka-nat addon)

  4. JSON-RPC over socket (modern, simpler)

  5. Implement queue-based GUI thread safety following neka-nat's pattern

  6. Provide comprehensive tool coverage:

  7. Execution: Python, macros

  8. Documents: create, open, save, list
  9. Objects: create, edit, delete, query
  10. PartDesign: pad, pocket, fillet, chamfer, patterns
  11. Part: primitives, booleans, transforms
  12. Export: STEP, STL, OBJ, FreeCAD native

  13. View: screenshot, camera control

  14. Add unique features:

  15. MCP Resources for document introspection

  16. MCP Prompts for guided workflows
  17. Macro development toolkit

  18. Workbench-specific tools

  19. Focus on developer experience:

  20. Debugging tools

  21. Error introspection
  22. Console history access
  23. Constraint validation

Sources