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.

Este proyecto proporciona una sólida integración entre los asistentes de IA y el software CAD FreeCAD mediante el Protocolo de Contexto de Modelo (MCP). Permite que las aplicaciones externas interactúen con FreeCAD a través de una interfaz estandarizada, ofreciendo múltiples métodos de conexión y herramientas especializadas.

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,122
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