FreeCAD Robust MCP Server
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
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.
The macros that were originally in this repo under the
/macrosdirectory have been permanently moved to two new GitHub repos:
FreeCAD Forum: addon discussion post
This section covers installation and usage for end users who want to use the Robust MCP Server with AI assistants.
Note: The Linux container and PyPI package are both named
freecad-robust-mcpwhich differs slightly from this git repository name.
pip install freecad-robust-mcp
git clone https://github.com/spkane/freecad-addon-robust-mcp-server.git
cd freecad-addon-robust-mcp-server
# Install mise via the Official mise installer script (if not already installed)
curl https://mise.run | sh
mise trust
mise install
just setup
Run the Robust MCP Server in a container. This is useful for isolated environments or when you don't want to install Python dependencies on your host.
# Pull from Docker Hub (when published)
docker pull spkane/freecad-robust-mcp
# Or build locally
git clone https://github.com/spkane/freecad-addon-robust-mcp-server.git
cd freecad-addon-robust-mcp-server
docker build -t freecad-robust-mcp .
# Or use just commands (if you have mise/just installed)
just docker::build # Build for local architecture
just docker::build-multi # Build multi-arch (amd64 + arm64)
Note: The containerized Robust MCP Server only supports xmlrpc and socket modes since FreeCAD runs on your host machine (not in the container). The container connects to FreeCAD via host.docker.internal.
Note: Embedded mode crashes on macOS because FreeCAD's FreeCAD.so links to @rpath/libpython3.11.dylib, which conflicts with external Python interpreters. Use xmlrpc or socket mode on macOS and Windows.
Add something like the following to your MCP client settings. For Claude Code, this is ~/.claude/claude_desktop_config.json or a project .mcp.json file:
{
"mcpServers": {
"freecad": {
"command": "freecad-mcp",
"env": {
"FREECAD_MODE": "xmlrpc"
}
}
}
}
If installed from source with mise/uv:
{
"mcpServers": {
"freecad": {
"command": "/path/to/mise/shims/uv",
"args": ["run", "--project", "/path/to/freecad-addon-robust-mcp-server", "freecad-mcp"],
"env": {
"FREECAD_MODE": "xmlrpc"
}
}
}
}
If using Docker:
{
"mcpServers": {
"freecad": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--add-host=host.docker.internal:host-gateway",
"-e", "FREECAD_MODE=xmlrpc",
"-e", "FREECAD_SOCKET_HOST=host.docker.internal",
"spkane/freecad-robust-mcp"
]
}
}
}
Docker configuration notes:
--rm removes the container after it exits-i keeps stdin open for MCP communication--add-host=host.docker.internal:host-gateway allows the container to connect to FreeCAD on your host (Linux only; macOS/Windows have this built-in)FREECAD_SOCKET_HOST=host.docker.internal tells the Robust MCP Server to connect to FreeCAD on your host machineBefore your AI assistant can connect, you need to start the MCP bridge inside FreeCAD:
Install the Robust MCP Bridge workbench via FreeCAD's Addon Manager:
Start the bridge:
You should see in the FreeCAD console:
MCP Bridge started!
- XML-RPC: localhost:9875
- Socket: localhost:9876
# Start FreeCAD with MCP bridge auto-started
just freecad::run-gui
# Or for headless/automation mode:
just freecad::run-headless
After starting the bridge, start/restart your MCP client (Claude Code, etc.) - it will connect automatically
To uninstall the Robust MCP Bridge workbench:
If you previously used older versions of this project, you may have legacy components installed. Run this command to check what's installed and get cleanup instructions:
just install::status
Remove any legacy files that may conflict with the workbench:
# macOS - remove legacy plugin and macro
rm -rf ~/Library/Application\ Support/FreeCAD/Mod/MCPBridge/
rm -f ~/Library/Application\ Support/FreeCAD/Macro/StartMCPBridge.FCMacro
# Linux - remove legacy plugin and macro
rm -rf ~/.local/share/FreeCAD/Mod/MCPBridge/
rm -f ~/.local/share/FreeCAD/Macro/StartMCPBridge.FCMacro
Connects to a running FreeCAD instance via XML-RPC. Works on all platforms.
FREECAD_MODE=xmlrpc freecad-mcp
Connects via JSON-RPC socket. Works on all platforms.
FREECAD_MODE=socket freecad-mcp
Run FreeCAD in console mode without GUI. Useful for automation.
# If installed from source:
just freecad::run-headless
Note: Screenshot and view features are not available in headless mode.
Runs FreeCAD in-process. Only works on Linux - crashes on macOS/Windows.
FREECAD_MODE=embedded freecad-mcp
The Robust MCP Server provides 150+ tools organized into categories. Tools marked with GUI require FreeCAD to be running in GUI mode; they will return an error in headless mode.
This section covers development setup, contributing, and working with the codebase.
# Clone the repository
git clone https://github.com/spkane/freecad-addon-robust-mcp-server.git
cd freecad-addon-robust-mcp-server
# Install mise via the Official mise installer script (if not already installed)
curl https://mise.run | sh
# Install all tools (Python 3.11, uv, just, pre-commit)
mise trust
mise install
# Set up the development environment
just setup
This installs:
Create a .mcp.json file in the project directory:
{
"mcpServers": {
"freecad": {
"command": "/path/to/mise/shims/uv",
"args": ["run", "--project", "/path/to/freecad-addon-robust-mcp-server", "freecad-mcp"],
"env": {
"FREECAD_MODE": "xmlrpc",
"FREECAD_SOCKET_HOST": "localhost",
"FREECAD_XMLRPC_PORT": "9875",
"PATH": "/path/to/mise/shims:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}
Replace the paths with your actual paths:
Finding your mise shims path:
mise where uv | sed 's|/installs/.*|/shims|'
# Example: /home/user/.local/share/mise/shims (on Linux) or ~/.local/share/mise/shims (on macOS)
Commands are organized into modules. Use just to see top-level commands, or just list-<module> to see module-specific commands.
# Show top-level commands and available modules
just
# Show commands in a specific module
just list-mcp # Robust MCP Server commands
just list-freecad # FreeCAD plugin/macro commands
just list-install # Installation commands
just list-quality # Code quality commands
just list-testing # Test commands
just list-docker # Docker commands
just list-documentation # Documentation commands
just list-dev # Development utilities
# List ALL commands from all modules
just list-all
# Install/update dependencies
just install::mcp-server
# Run all checks (linting, type checking, tests)
just all
# Quality commands
just quality::lint # Run ruff linter
just quality::typecheck # Run mypy type checker
just quality::format # Format code
just quality::check # Run all pre-commit hooks
# Testing commands
just testing::unit # Run unit tests
just testing::cov # Run tests with coverage
just testing::integration # Run integration tests
# Run the Robust MCP Server (or with debug logging)
just mcp::run
just mcp::run-debug
# Docker commands
just docker::build # Build image for local architecture
just docker::build-multi # Build multi-arch image (amd64 + arm64)
just docker::run # Run container
# Start FreeCAD with auto-started bridge
just freecad::run-gui
just freecad::run-headless
# Unit tests only (no FreeCAD required)
just testing::unit
# Unit tests with coverage
just testing::cov
# Integration tests (requires running FreeCAD bridge)
just testing::integration
# Integration tests with automatic FreeCAD startup
just testing::integration-auto
The project uses strict code quality checks via pre-commit:
# Run all pre-commit hooks
just quality::check
# Run security/secrets scans
just quality::security
just quality::secrets
See the detailed architecture document for design documentation covering:
This project was developed after analyzing several existing FreeCAD Robust MCP implementations. We are grateful to these projects for their pioneering work and the ideas they contributed to the FreeCAD + AI ecosystem:
neka-nat/freecad-mcp (MIT License) - The queue-based thread safety pattern and XML-RPC protocol design (port 9875) were directly inspired by this project. Our implementation maintains protocol compatibility while being a complete rewrite with additional features.
jango-blockchained/mcp-freecad - Inspired our connection recovery mechanisms and multi-mode architecture approach.
contextform/freecad-mcp - Informed our comprehensive PartDesign and Part workbench tool coverage.
ATOI-Ming/FreeCAD-MCP - Inspired our macro development toolkit including templates, validation, and automatic imports.
bonninr/freecad_mcp - Influenced our simple socket-based communication approach.
See docs/COMPARISON.md for a detailed analysis of these implementations and the design decisions they informed.
MIT License - see LICENSE for details.
The FreeCAD Robust MCP server and MCP Bridge Workbench/Addon
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Freecad Addon Robust 透過 stdio 在本機執行。
上次檢查時間:2026-11-17。 The FreeCAD Robust MCP server and MCP Bridge Workbench/Addon