mcp-freecad

🛠️ MCP-FreeCAD Integration

Status: Active Development - Clean, organized codebase with multiple connection methods and comprehensive tool providers.

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

{
  "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

# 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

🧠 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)

# 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 -m src.mcp_freecad.main

# Or with custom config
python -m src.mcp_freecad.main --config my_config.json --debug

🏗️ 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:

🚀 Launcher (Recommended) - Uses AppImage with AppRun
🔌 Server - Socket-based connection to FreeCAD server
🌉 Bridge - CLI-based connection using FreeCAD executable
📡 RPC - XML-RPC connection to FreeCAD
📦 Wrapper - Subprocess wrapper connection
🎭 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

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

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

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`)

{
  "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

{
  "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

Create a new tool provider in src/mcp_freecad/tools/
Inherit from ToolProvider base class
Implement required methods (tool_schema, execute_tool)
Register in TOOL_PROVIDERS in __init__.py

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

# 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

# Build and run with Docker Compose
docker compose up

# Build from scratch
docker compose build --no-cache
docker compose up

📚 Documentation

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📄 License

This project is licensed under the MIT License - see the 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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

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.

Related MCP Servers

BlenderMCP
ahujasid
A
security
A
license
A
quality
Connects Blender to Claude AI through the Model Context Protocol (MCP), allowing Claude to directly interact with and control Blender for AI-assisted 3D modeling, scene manipulation, and rendering.
Last updated -
17
13,041
MIT License
FreeCAD MCP
bonninr
-
security
A
license
-
quality
A FreeCAD addon that implements the Model Context Protocol (MCP) to enable communication between FreeCAD and Claude AI through Claude Desktop.
Last updated -
89
MIT License
Revit MCP
revit-mcp
A
security
A
license
A
quality
Allows AI to interact with Autodesk Revit via the MCP protocol, enabling retrieval of project data and automation of tasks like creating, modifying, and deleting elements.
Last updated -
13
109
MIT License
Revit MCP Server
ideook
A
security
A
license
A
quality
Allows AI assistants to interact with Autodesk Revit through the MCP protocol, enabling the AI to create, modify, and delete elements in Revit projects.
Last updated -
15
32
1
MIT License

View all related MCP servers