Content
# Model Context Protocol (MCP) Server for FreeCAD Automation
Expose FreeCAD’s internal geometric API to AI agents for programmatic generative design and rapid prototyping.
---
## 1. Value Proposition
A lightweight Python bridge implementing Anthropic's **Model Context Protocol (MCP)**, allowing LLM agents (such as Claude Desktop or Gemini) to execute natural language generative CAD design directly inside an active FreeCAD session.
---
## 2. Key Features
* **Generative CAD execution**: Direct Python console access for structural bracket compilation and geometric placement.
* **Predefined Parametric Blueprints**: Quick tool actions for solid box casing, cylinders, and structural mount brackets.
* **Lossless XML-RPC Link**: Clean RPC network loop to prevent session blocking.
* **Fully Audited Configs**: Local configuration templates with path placeholders to prevent dev machine data leaks.
---
## 3. Visual Demonstration & Screenshot
---
## 4. Technical Architecture
```
+-----------------------------------+
| AI Client (e.g., Claude Desktop) |
+-----------------------------------+
|
| (Model Context Protocol / Stdio)
v
+-----------------------------------+
| FastMCP Bridge Server (bridge.py)| <-- This Project
+-----------------------------------+
|
| (XML-RPC over HTTP - port 8000)
v
+-----------------------------------+
| FreeCAD Instance (Active Session)|
+-----------------------------------+
```
The bridge server intercepts stdio JSON-RPC commands from the AI client, translates them into Python execution code blocks, and dispatches them over a local HTTP connection to FreeCAD's XML-RPC server workbench.
---
## 5. Installation Instructions & Quick Start
### Prerequisites
1. **FreeCAD**: Standard installation (v0.20+ recommended).
2. **RPC Server Workbench**: Install the "Robust MCP Bridge" or standard RPC Server addon via FreeCAD's Addon Manager. Set it to listen on `http://127.0.0.1:8000`.
### Setup
1. Clone the repository and install requirements:
```bash
pip install -r requirements.txt
```
2. Run the bridge server:
```bash
python3 bridge.py
```
3. Configure your Claude Desktop client config (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"freecad-automation": {
"command": "python3",
"args": [
"/path/to/your/freecad-mcp-agent-bridge/bridge.py"
],
"env": {
"FREECAD_SERVER_URL": "http://127.0.0.1:8000"
}
}
}
}
```
---
## 6. Example Usage
Prompting the AI agent:
> *"Create a mounting bracket that is 60mm wide, 100mm long, and 4mm thick with a centered mounting hole of 3.5mm radius."*
The AI will call the tool `create_bracket_part(width=60, length=100, thickness=4, hole_radius=3.5)` which compiles the bracket instantly inside FreeCAD.
---
## 7. FAQ Section
### Q: Why does the server time out?
Ensure that FreeCAD is running and that the XML-RPC server workbench is actively listening on port 8000. See [Troubleshooting Guide](./docs/troubleshooting.md).
### Q: Can I execute custom python scripts?
Yes, use the `execute_freecad_python` tool to pass raw python script blocks into FreeCAD.
---
## 8. Related Projects & Topic Cluster
Check out our other projects in the GN3D Studio ecosystem:
* [cadquery-parametric-casings](https://github.com/gn3dstudio/cadquery-parametric-casings) - Programmatic CAD blueprint scripts.
* [industrial-fdm-print-profiles](https://github.com/gn3dstudio/industrial-fdm-print-profiles) - High-performance composite print configs.
* [fdm-print-failure-analysis](https://github.com/gn3dstudio/fdm-print-failure-analysis) - Empirical datasets for mechanical print failures.
---
## 9. Related Resources
* [Troubleshooting Guide](./docs/troubleshooting.md)
* [Changelog](./CHANGELOG.md)
* [Academic Citation Profile](./CITATION.cff)
* [MIT License](./LICENSE)
---
## About GN3D Studio
**Industrial 3D Printing & Rapid Prototyping**
* **Website**: [https://gn3dstudio.com](https://gn3dstudio.com)
* **Services**:
* Custom 3D Printing
* Rapid Prototyping
* Functional Prototypes
* Engineering Parts
* CAD Automation
* **Location**: Ho Chi Minh City, Vietnam
