Sean P. KaneandGitHub
6a6cad9e65
* FreeCAD addon support for Workbench and Plugins * docs: refactor docs and clean up linters, etc. * Remove mdformat * test: improve test coverage * test:Lots of general fixes * chore: more general fixes
127 lines
3.4 KiB
Markdown
127 lines
3.4 KiB
Markdown
# Installation
|
|
|
|
This guide covers installing the FreeCAD MCP Server and connecting it to your AI assistant.
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- **FreeCAD** 0.21+ or 1.0+ (with Python 3.11)
|
|
- **Python 3.11** (must match FreeCAD's bundled Python version)
|
|
- An **MCP-compatible AI assistant** (Claude Code, Cursor, etc.)
|
|
|
|
---
|
|
|
|
## Installation Methods
|
|
|
|
### Method 1: pip (Recommended)
|
|
|
|
The simplest way to install the MCP server:
|
|
|
|
```bash
|
|
pip install freecad-robust-mcp
|
|
```
|
|
|
|
### Method 2: From Source (for Development)
|
|
|
|
```bash
|
|
git clone https://github.com/spkane/freecad-robust-mcp-and-more.git
|
|
cd freecad-robust-mcp-and-more
|
|
|
|
# Install mise (if not already installed)
|
|
curl https://mise.run | sh
|
|
|
|
mise trust
|
|
mise install
|
|
just setup
|
|
```
|
|
|
|
### Method 3: Docker
|
|
|
|
Run the MCP server in a container:
|
|
|
|
```bash
|
|
# Pull from Docker Hub
|
|
docker pull spkane/freecad-robust-mcp
|
|
|
|
# Or build locally
|
|
docker build -t freecad-robust-mcp .
|
|
```
|
|
|
|
**Note:** The Docker container runs the MCP server only—it does not include FreeCAD itself. You must run FreeCAD with the MCP Bridge workbench on your host machine (or in a separate container) and configure the MCP server to connect via `xmlrpc` or `socket` mode.
|
|
|
|
**Why embedded mode doesn't work with Docker:** Embedded mode requires FreeCAD and the MCP server to run in the same process, which is impossible when FreeCAD runs on the host and the MCP server runs inside a Docker container. Additionally, embedded mode fails on macOS due to ABI incompatibility with FreeCAD's bundled Python libraries (`libpython3.11.dylib`). Always use `xmlrpc` or `socket` mode for Docker deployments.
|
|
|
|
---
|
|
|
|
## Installing the MCP Bridge Workbench
|
|
|
|
The MCP Bridge Workbench runs inside FreeCAD and provides the connection point for the MCP server.
|
|
|
|
### Via FreeCAD Addon Manager (Recommended)
|
|
|
|
1. Open FreeCAD
|
|
1. Go to **Tools > Addon Manager**
|
|
1. Search for "FreeCAD MCP and More" or "MCP Bridge"
|
|
1. Click **Install**
|
|
1. Restart FreeCAD
|
|
|
|
### Manual Installation
|
|
|
|
1. Download the latest release from [GitHub Releases](https://github.com/spkane/freecad-robust-mcp-and-more/releases)
|
|
1. Extract to your FreeCAD Mod directory:
|
|
- **Linux:** `~/.local/share/FreeCAD/Mod/`
|
|
- **macOS:** `~/Library/Application Support/FreeCAD/Mod/`
|
|
- **Windows:** `%APPDATA%\FreeCAD\Mod\`
|
|
1. Restart FreeCAD
|
|
|
|
---
|
|
|
|
## Verifying Installation
|
|
|
|
After installation, verify everything is working:
|
|
|
|
### Step 1: Start FreeCAD with the MCP Bridge
|
|
|
|
1. **Start FreeCAD** and select the **MCP Bridge** workbench from the workbench selector dropdown
|
|
1. **Click "Start MCP Bridge"** in the toolbar (or use the MCP Bridge menu)
|
|
1. Check the FreeCAD console for confirmation messages:
|
|
|
|
```text
|
|
MCP Bridge started!
|
|
- XML-RPC: localhost:9875
|
|
- Socket: localhost:9876
|
|
```
|
|
|
|
### Step 2: Verify the MCP Server
|
|
|
|
Test that the MCP server command is available:
|
|
|
|
```bash
|
|
# With pip installation
|
|
freecad-mcp --help
|
|
|
|
# With source installation
|
|
uv run freecad-mcp --help
|
|
```
|
|
|
|
### Step 3: Test the Connection
|
|
|
|
With FreeCAD running and the bridge started, you can verify connectivity:
|
|
|
|
```bash
|
|
# Quick connectivity test using curl (XML-RPC)
|
|
curl -X POST http://localhost:9875 \
|
|
-H "Content-Type: text/xml" \
|
|
-d '<?xml version="1.0"?><methodCall><methodName>ping</methodName></methodCall>'
|
|
```
|
|
|
|
A successful response indicates the bridge is working correctly.
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- [Configuration](configuration.md) - Set up environment variables and MCP client settings
|
|
- [Quick Start](quickstart.md) - Create your first model with AI assistance
|