Content
# 🛠️ MCP-FreeCAD Integration
> **Status:** Active Development - Clean, organized codebase with multiple connection methods and comprehensive tool providers.
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
[](https://flake8.pycqa.org/en/latest/)
[]()
This project provides a robust integration between AI assistants and FreeCAD CAD software using the **Model Context Protocol (MCP)**. It allows external applications to interact with FreeCAD through a standardized interface, offering multiple connection methods and specialized tools.
---
## 🤖 **AI Provider Models (2025)**
The MCP-FreeCAD integration supports multiple AI providers with the latest 2025 models. Choose the right model for your specific use case:
### **OpenAI Models**
#### **Production Models:**
- **gpt-4o** - Default multimodal model (text, image, audio)
- Context: 128K tokens
- Pricing: ~$5 per 1M input tokens
- Best for: General CAD tasks, multimodal interactions
- **gpt-4.1** - Next-generation with 1M token context
- Features: Text, Image, Audio, Video support
- Pricing: ~$2.5 per 1M input tokens
- Best for: Complex CAD projects, large document analysis
- **gpt-4-turbo** - Fast, cost-effective
- Context: 128K tokens
- Best for: High-volume operations, batch processing
#### **Reasoning Models:**
- **o3** - Advanced reasoning for complex CAD logic
- Pricing: ~$10 per 1M input tokens
- Best for: Complex geometry calculations, design optimization
- **o4-mini** / **o4-mini-high** - Cost-effective reasoning
- Pricing: ~$0.15 per 1M input tokens
- Best for: Simple calculations, quick iterations
### **Anthropic Claude Models**
#### **Claude 4 Series (2025):**
- **claude-opus-4** - Most advanced model
- Max Context: 200K tokens
- Pricing: $15/$75 per million tokens (input/output)
- Features: Extended thinking, tool use, memory handling
- Best for: Complex CAD workflows, autonomous design tasks
- **claude-sonnet-4** - Balanced efficiency
- Max Context: 200K tokens
- Pricing: $3/$15 per million tokens
- Features: Superior coding, hybrid reasoning
- Best for: General CAD operations, scripting assistance
- **claude-haiku-3.5** - Fast, lightweight
- Best for: Quick queries, simple operations
### **Google AI Models**
#### **Gemini 2.5 Series (Latest):**
- **gemini-2.5-pro-preview-05-06** - Most advanced
- Context: 1M tokens
- Features: Enhanced reasoning, thinking mode
- Best for: Complex CAD analysis, large assemblies
- **gemini-2.5-flash-preview-04-17** - Performance optimized
- Features: Adaptive thinking, cost-effective
- Best for: Balanced performance and cost
#### **Gemini 2.0 Series (Stable):**
- **gemini-2.0-flash-001** - Production ready
- Features: 2x faster than Gemini 1.5 Pro
- Best for: Real-time CAD assistance
- **gemini-2.0-flash-lite** - Cost-optimized
- Best for: High-volume, simple operations
### **OpenRouter (Unified Access)**
OpenRouter provides access to all models through a single API:
#### **Model Format:** `provider/model-name`
**Popular Models:**
- `anthropic/claude-sonnet-4` - Recommended general use
- `openai/gpt-4o` - OpenAI's flagship
- `google/gemini-2.5-pro-preview` - Google's latest
**Free Models (50-1000 requests/day):**
- `deepseek/deepseek-r1` - Advanced reasoning
- `deepseek/deepseek-v3` - General purpose
- `google/gemini-2.5-flash-preview` - Google free tier
### **Model Selection Guide**
| **Use Case** | **Recommended Model** | **Alternative** |
|-------------|---------------------|----------------|
| **General CAD Work** | `claude-sonnet-4` | `gpt-4o`, `gemini-2.0-flash-001` |
| **Complex Reasoning** | `claude-opus-4` | `o3`, `gemini-2.5-pro-preview-05-06` |
| **Multimodal Tasks** | `gpt-4o` | `gpt-4.1`, `claude-opus-4` |
| **Cost-Effective** | `o4-mini` | `claude-haiku-3.5`, `gemini-2.0-flash-lite` |
| **High Volume** | `gpt-4-turbo` | `claude-sonnet-4`, `gemini-2.0-flash-001` |
| **Free Usage** | `deepseek/deepseek-r1` | `google/gemini-2.5-flash-preview` |
### **Configuration Example**
```json
{
"providers": {
"anthropic": {
"enabled": true,
"model": "claude-sonnet-4",
"thinking_mode": true,
"max_tokens": 64000
},
"openai": {
"enabled": true,
"model": "gpt-4o",
"max_tokens": 32000
},
"google": {
"enabled": true,
"model": "gemini-2.0-flash-001",
"thinking_mode": true
},
"openrouter": {
"enabled": true,
"model": "anthropic/claude-sonnet-4",
"free_models": ["deepseek/deepseek-r1"]
}
}
}
```
### **API Usage Examples**
```python
# Using specific provider
from freecad_ai import CADAssistant
# Initialize with Claude Sonnet 4
assistant = CADAssistant(provider="anthropic", model="claude-sonnet-4")
# Create complex geometry
result = assistant.generate_cad_script(
"Create a parametric gear with 20 teeth, 5mm module, and 20° pressure angle"
)
# Using OpenRouter for cost optimization
assistant_free = CADAssistant(
provider="openrouter",
model="deepseek/deepseek-r1"
)
# Quick operations with free model
result = assistant_free.create_primitive("box", length=10, width=5, height=3)
```
---
## 🚀 **Quick Start**
### Option 1: FreeCAD Addon (Recommended for Users)
For the best user experience with GUI integration:
📦 **[FreeCAD MCP Integration Addon](freecad-ai/README.md)**
- 🧠 **Claude 4 with Thinking Mode** - Advanced AI reasoning
- 🤖 **Multi-Provider Support** - Claude, Gemini, OpenRouter with 13+ models
- 🎨 **Modern GUI** - Professional tabbed interface
- 🔗 **Universal Connections** - All MCP connection methods
- 📊 **Performance Monitoring** - Real-time diagnostics
### Option 2: MCP Server (For Developers/Integration)
```bash
# Clone the repository
git clone https://github.com/jango-blockchained/mcp-freecad.git
cd mcp-freecad
# Install dependencies
pip install -r requirements.txt
# Start the MCP server
python mcp_server.py
# Or with FastMCP mode (lightweight, ideal for Cursor IDE)
python mcp_server.py --mode fastmcp
# Or with custom config and debug logging
python mcp_server.py --config my_config.json --debug
```
python -m src.mcp_freecad.main --config my_config.json --debug
```
### Option 3: FastMCP Server (Cursor IDE & Latest Best Practices)
**✨ NEW: Updated to FastMCP 2.13.0.2** - Modern, declarative MCP server implementation.
```bash
# Start the FastMCP server for Cursor IDE
python cursor_mcp_server.py
# Or run the example to see available tools
python example_fastmcp_usage.py --all
```
**Key Features:**
- 🎯 **Declarative API** - Simple `@mcp.tool()` and `@mcp.resource()` decorators
- 🔒 **Type Safe** - Automatic schema generation from type hints
- 🚀 **Best Practices** - Follows FastMCP 2.13 recommended patterns
- ✅ **Well Tested** - Comprehensive test suite with 100% pass rate
- 📚 **Great Documentation** - See [FASTMCP_IMPLEMENTATION.md](docs/FASTMCP_IMPLEMENTATION.md)
**Available Tools:**
- `test_connection` - Test FreeCAD connectivity
- `create_box` - Create box primitives
- `create_cylinder` - Create cylinders
- `create_sphere` - Create spheres
- `create_document` - Manage FreeCAD documents
**Resources:**
- `freecad://status` - Get server status and FreeCAD availability
For detailed usage, see the [FastMCP Implementation Guide](docs/FASTMCP_IMPLEMENTATION.md).
---
## 🏗️ **Architecture Overview**
### Core Components
```
src/mcp_freecad/
├── main.py # Main entry point
├── __init__.py # Package exports and registry
├── client/ # FreeCAD connection management
│ └── freecad_connection_manager.py
├── server/ # MCP server implementation
│ └── freecad_mcp_server.py
├── tools/ # Tool providers
│ ├── base.py # Base tool provider class
│ ├── primitives.py # Primitive shapes (box, cylinder, etc.)
│ ├── model_manipulation.py # Transform, boolean ops, etc.
│ ├── export_import.py # File format handling
│ ├── measurement.py # Analysis tools
│ └── code_generator.py # Code generation
├── core/ # Core infrastructure
│ ├── server.py # FastAPI-based server
│ ├── cache.py # Resource caching
│ ├── diagnostics.py # Performance monitoring
│ └── recovery.py # Connection recovery
└── connections/ # Connection backends
```
### Connection Methods
The system supports multiple ways to connect to FreeCAD:
1. **🚀 Launcher** (Recommended) - Uses AppImage with AppRun
2. **🔌 Server** - Socket-based connection to FreeCAD server
3. **🌉 Bridge** - CLI-based connection using FreeCAD executable
4. **📡 RPC** - XML-RPC connection to FreeCAD
5. **📦 Wrapper** - Subprocess wrapper connection
6. **🎭 Mock** - For testing without FreeCAD
---
## 🛠️ **Available Tools**
### Primitive Creation
- `create_box` - Create box primitives
- `create_cylinder` - Create cylinders
- `create_sphere` - Create spheres
- `create_cone` - Create cones
### Model Manipulation
- `transform` - Move, rotate objects
- `boolean_operation` - Union, difference, intersection
- `fillet_edge` - Round edges
- `chamfer_edge` - Chamfer edges
- `mirror` - Mirror objects across planes
- `scale` - Scale objects uniformly or non-uniformly
### Document Management
- `create_document` - Create new documents
- `list_documents` - List open documents
- `list_objects` - List objects in documents
### Export/Import
- `export_stl` - Export to STL format
- Additional formats coming soon
---
## 📋 **Usage Examples**
### Python API
```python
from src.mcp_freecad import FreeCADConnection, PrimitiveToolProvider
# Create connection (auto-selects best method)
fc = FreeCADConnection(auto_connect=True)
if fc.is_connected():
print(f"Connected via: {fc.get_connection_type()}")
# Create a document
doc_name = fc.create_document("MyProject")
# Create objects
box = fc.create_box(length=20, width=10, height=5)
cylinder = fc.create_cylinder(radius=3, height=10)
# Export
fc.export_stl(box, "my_box.stl")
```
### Tool Provider Usage
```python
from src.mcp_freecad.tools.primitives import PrimitiveToolProvider
# Initialize tool provider
primitives = PrimitiveToolProvider()
# Execute tools
result = await primitives.execute_tool("create_box", {
"length": 10.0,
"width": 5.0,
"height": 3.0
})
print(f"Created: {result.result['object_id']}")
```
### MCP Server Integration
```python
from src.mcp_freecad.core.server import MCPServer
from src.mcp_freecad import TOOL_PROVIDERS
# Setup server
server = MCPServer()
# Register tool providers
server.register_tool("primitives", TOOL_PROVIDERS["primitives"]())
server.register_tool("model_manipulation", TOOL_PROVIDERS["model_manipulation"]())
# Initialize and run
await server.initialize()
```
---
## ⚙️ **Configuration**
### Basic Configuration (`config.json`)
```json
{
"server": {
"name": "mcp-freecad-server",
"version": "0.7.11"
},
"freecad": {
"connection_method": "auto",
"host": "localhost",
"port": 12345,
"freecad_path": "freecad"
},
"tools": {
"enable_primitives": true,
"enable_model_manipulation": true,
"enable_export_import": true
}
}
```
### Connection Method Configuration
```json
{
"freecad": {
"connection_method": "launcher",
"use_apprun": true,
"apprun_path": "/path/to/squashfs-root/AppRun",
"script_path": "/path/to/freecad_launcher_script.py"
}
}
```
---
## 🔧 **Development**
### Project Structure
- **`src/mcp_freecad/`** - Main package
- **`freecad-ai/`** - FreeCAD GUI addon
- **`tests/`** - Test suite
- **`docs/`** - Documentation
- **`scripts/`** - Setup and utility scripts
### Adding New Tools
1. Create a new tool provider in `src/mcp_freecad/tools/`
2. Inherit from `ToolProvider` base class
3. Implement required methods (`tool_schema`, `execute_tool`)
4. Register in `TOOL_PROVIDERS` in `__init__.py`
```python
from .base import ToolProvider, ToolResult, ToolSchema
class MyToolProvider(ToolProvider):
@property
def tool_schema(self) -> ToolSchema:
return ToolSchema(
name="my_tool",
description="My custom tool",
parameters={...},
returns={...}
)
async def execute_tool(self, tool_id: str, params: Dict[str, Any]) -> ToolResult:
# Implementation
return self.format_result(status="success", result=result)
```
### Testing
```bash
# Run tests
python -m pytest tests/
# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html
# Run specific test
python -m pytest tests/test_primitives.py -v
```
---
## 🐳 **Docker Support**
```bash
# Build and run with Docker Compose
docker compose up
# Build from scratch
docker compose build --no-cache
docker compose up
```
---
## 📚 **Documentation**
- [FreeCAD Integration Guide](docs/FREECAD_INTEGRATION.md)
- [Connection Methods](docs/CONNECTION_METHODS.md)
- [Tool Development](docs/TOOL_DEVELOPMENT.md)
- [Configuration Reference](docs/CONFIGURATION.md)
---
## 🤝 **Contributing**
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
---
## 📄 **License**
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## 🙏 **Acknowledgments**
- FreeCAD development team for the excellent CAD software
- Anthropic for the Model Context Protocol (MCP) framework
- Contributors and community members
---
<div align="center">
<sub>
🛠️ <strong>MCP-FreeCAD Integration</strong> - Bridging AI and CAD through advanced connectivity<br>
Crafted with ❤️ by jango-blockchained • 2025
</sub>
</div>
