Alimenter votre agent
Installation de l'éditeur. Ce n'est pas un endpoint PlugMCP.
Host a copy with our keys and logs.
Pas encore de version packagée dans le registre. Suivez le README du dépôt.
URL distante ou commande sur votre machine ? Ce qui distingue les deux installations
Exécuter sur PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LancerAn 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
Outils
Pas encore de liste d'outils. Les serveurs distants en obtiennent une après le premier contrôle d'état.
FAQ
Copiez sur cette page la configuration stdio pour Cursor, Claude Desktop, Claude Code ou VS Code. Elle utilise l'installation de l'éditeur, pas un proxy PlugMCP.
Aucune variable d'environnement requise n'est indiquée sur cette fiche.
Freecad Addon Robust s'exécute en local via stdio.
Dernière vérification : 2026-11-17. The FreeCAD Robust MCP server and MCP Bridge Workbench/Addon