FreeCAD MCP Server

Let AI design 3D models in FreeCAD through natural language.

FreeCAD MCP Server bridges FreeCAD and AI assistants via the Model Context Protocol (MCP). It exposes 39 CAD tools that let AI agents create, modify, query, and export 3D models — all through natural language conversation.

Why?

Traditional CAD requires learning complex software UIs. With FreeCAD MCP, you can:

• Design by conversation — describe what you want, AI builds it

• Iterate rapidly — tweak dimensions, add features, and compare variants in seconds

• Automate repetitive tasks — parameterized modeling without clicking through menus

• Integrate into workflows — connect CAD with code review, documentation, and CI/CD

Related MCP server: FreeCAD Robust MCP Server

Demo

Tell your AI assistant:

"Create a 100x60x20mm enclosure base with 2mm wall thickness and a central screen cutout"

The AI will call FreeCAD tools automatically:

new_document → create_box(100, 60, 20) → create_box(96, 56, 18)
→ translate → boolean_cut → export_step("enclosure_base.step")

Quick Start

1. Install

git clone https://github.com/your-username/freecad-mcp.git
cd freecad-mcp

2. Install MCP dependencies with FreeCAD's Python

# macOS
/Applications/FreeCAD.app/Contents/Resources/bin/python -m pip install -r requirements.txt

# Windows
E:\Freecad\bin\python.exe -m pip install -r requirements.txt

# Linux (adjust path to your FreeCAD installation)
freecadpython -m pip install -r requirements.txt

Important: You must use FreeCAD's bundled Python, not the system Python. FreeCAD's FreeCAD.so/FreeCAD.pyd is a C++ extension that only loads in FreeCAD's Python environment.

3. Configure your MCP client

opencode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "freecad-modeling": {
      "type": "local",
      "command": ["bash", "/path/to/freecad-mcp/run_mcp.sh"],
      "enabled": true
    }
  }
}

Claude Desktop / Cline / Cursor

Add to your MCP configuration:

{
  "mcpServers": {
    "freecad-modeling": {
      "command": "bash",
      "args": ["/path/to/freecad-mcp/run_mcp.sh"],
      "cwd": "/path/to/freecad-mcp"
    }
  }
}

Windows users: Replace bash with the path to run_server.bat.

4. Restart your client

The FreeCAD tools will now be available in your AI conversations.

Available Tools (39)

Document Management

Primitive Shapes

Boolean Operations

Transforms

Sketch & Features

Measurement & Inspection

Export

Example Workflows

Enclosure with mounting holes

"Design a 120×80×25mm electronics enclosure. Base should have 2mm walls, internal ribs for PCB mounting, and four M3 screw posts in the corners. Top should be a flat lid with matching screw holes. Export both as STEP."

Parametric bracket

"Create an L-shaped bracket, 50mm on each leg, 5mm thick, with a 10mm fillet on the inner corner and two M4 through-holes on each leg. Measure the volume and export as STL."

Mechanical part with revolve

"Create a shaft collar by revolving a profile: 15mm outer diameter, 8mm bore, 12mm wide, with a 1mm chamfer on both edges. Export as STEP."

Project Structure

freecad-mcp/
├── main.py                 # Entry point
├── freecad_mcp/
│   ├── server.py           # MCP server + tool registration
│   ├── runner.py           # Safe execution wrapper
│   └── tools/
│       ├── document.py     # Document management
│       ├── primitives.py   # Shape creation
│       ├── boolean.py      # Boolean operations
│       ├── transform.py    # Transforms
│       ├── sketch.py       # Sketch features
│       ├── measure.py      # Measurement
│       └── export.py       # File export
├── run_mcp.sh              # macOS/Linux launcher
├── run_server.bat          # Windows launcher
├── requirements.txt        # Python dependencies
└── README.md

Requirements

Configuration

Custom FreeCAD path

Edit run_mcp.sh (macOS/Linux) or run_server.bat (Windows) to point to your FreeCAD Python installation.

Units

All dimensions are in millimeters (mm). The coordinate system is right-handed with Z-axis pointing up.

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/my-feature)

3. Make your changes

4. Run the smoke test: /Applications/FreeCAD.app/Contents/Resources/bin/python scripts/test_basic.py

5. Submit a pull request

Ideas for contributions

• Add new tools (e.g., pattern arrays, surface operations, assembly)

• Improve error handling and validation

• Add support for FreeCAD 1.0 (earlier Python versions)

• Create example projects / tutorials

• Add unit tests

License

MIT

Acknowledgments

• FreeCAD — The open-source parametric 3D CAD modeler

• Model Context Protocol — The protocol for AI-tool integration

• MCP Python SDK — Official Python implementation