spkane/freecad-robust-mcp repository overview

⁠FreeCAD Robust MCP Server

An MCP (Model Context Protocol)⁠ server that enables integration between AI assistants (Claude, GPT, and other MCP-compatible tools) and FreeCAD⁠, allowing AI-assisted development and debugging of 3D models, macros, and workbenches.

⁠Features

• 82+ MCP Tools: Comprehensive CAD operations including primitives, PartDesign, booleans, export
• Multiple Connection Modes: XML-RPC (recommended), JSON-RPC socket, or embedded
• GUI & Headless Support: Full modeling in headless mode, plus screenshots/colors in GUI mode
• Macro Development: Create, edit, run, and template FreeCAD macros via MCP

⁠Quick Start

docker pull spkane/freecad-robust-mcp:latest

⁠Running with Claude Desktop (macOS/Windows)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "freecad": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "FREECAD_MODE=xmlrpc",
        "-e", "FREECAD_SOCKET_HOST=host.docker.internal",
        "spkane/freecad-robust-mcp:latest"
      ]
    }
  }
}

⁠Linux Users

host.docker.internal is only available on Docker Desktop (macOS/Windows). On Linux Docker Engine, use one of these alternatives:

Option 1: Host networking (recommended)

docker run -i --rm --network=host \
  -e FREECAD_MODE=xmlrpc \
  -e FREECAD_SOCKET_HOST=localhost \
  spkane/freecad-robust-mcp:latest

Option 2: Use host IP address

docker run -i --rm \
  -e FREECAD_MODE=xmlrpc \
  -e FREECAD_SOCKET_HOST=192.168.1.100 \
  spkane/freecad-robust-mcp:latest

Option 3: Add host gateway (Docker 20.10+)

docker run -i --rm --add-host=host.docker.internal:host-gateway \
  -e FREECAD_MODE=xmlrpc \
  -e FREECAD_SOCKET_HOST=host.docker.internal \
  spkane/freecad-robust-mcp:latest

⁠Connection Modes

⁠Environment Variables

⁠Starting FreeCAD with MCP Bridge

Before using this Docker image, start FreeCAD with the MCP bridge:

1. Open FreeCAD
2. Go to Macro → Macros → StartMCPBridge (or run from Python console)
3. The bridge will start listening on ports 9875 (XML-RPC) and 9876 (Socket)

⁠Full Documentation

📖 For complete documentation, examples, and source code, visit:

https://github.com/spkane/freecad-robust-mcp-and-more⁠

⁠License

MIT License - see LICENSE⁠ for details.