freecad-mcp by Twine2546 - MCP Server

FreeCAD MCP Server

Model Context Protocol (MCP) server for AI-assisted 3D CAD modeling with FreeCAD. This implementation enables Claude Desktop and other MCP clients to control FreeCAD programmatically for generative design workflows.

Features

Document Management: Create and manage FreeCAD documents
Object Operations: Create, edit, and delete 3D objects
Code Execution: Execute arbitrary Python code in FreeCAD environment
Visual Feedback: Get screenshots of the 3D viewport
Export Support: Export models to STEP, STL, and other formats
Docker Support: Run as containerized service connecting to FreeCAD

Architecture

This implementation consists of two components:

FreeCAD RPC Server (freecad_rpc_server.py): Runs inside FreeCAD container and exposes functionality via XML-RPC
MCP Server (src/freecad_mcp/): Connects to FreeCAD RPC and provides MCP interface for AI clients

Claude Desktop <-> MCP Server <-> XML-RPC <-> FreeCAD Container

Installation

Prerequisites

Python 3.10+
Docker (optional, recommended)
FreeCAD running in a container with RPC server enabled

Setup FreeCAD RPC Server

Copy freecad_rpc_server.py to your FreeCAD container:

docker cp freecad_rpc_server.py your-freecad-container:/home/freecad/

Start the RPC server inside FreeCAD:

docker exec -it your-freecad-container freecad -c /home/freecad/freecad_rpc_server.py

Or add to your FreeCAD container's startup script.

Ensure port 9000 is exposed in your FreeCAD container configuration.

Install MCP Server

Option 1: Docker (Recommended)

# Build and run
docker-compose up -d

# Or with custom FreeCAD host
docker run -e FREECAD_HOST=192.168.1.138 -e FREECAD_PORT=9000 freecad-mcp

Option 2: Local Installation

pip install -e .

# Run with environment variables
export FREECAD_HOST=localhost
export FREECAD_PORT=9000
python -m freecad_mcp

Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "freecad": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network", "freecad-network",
        "-e", "FREECAD_HOST=freecad",
        "-e", "FREECAD_PORT=9000",
        "freecad-mcp"
      ]
    }
  }
}

Or for local installation:

{
  "mcpServers": {
    "freecad": {
      "command": "python",
      "args": ["-m", "freecad_mcp"],
      "env": {
        "FREECAD_HOST": "localhost",
        "FREECAD_PORT": "9000"
      }
    }
  }
}

Available Tools

Document Management

create_document: Create a new FreeCAD document
save_document: Save the active document
export_document: Export to STEP, STL, etc.

Object Operations

create_object: Create objects (Box, Cylinder, Sphere, etc.)
edit_object: Modify object properties
delete_object: Remove objects from document
get_objects: List all objects in document
get_object: Get detailed object information

Advanced

execute_code: Execute Python code in FreeCAD environment
get_view: Capture 3D viewport screenshot

Usage Examples

Create a Simple Box

Claude: Create a box with dimensions 10x10x10

The MCP server will:

Create a new document
Add a Part::Box object
Set Length, Width, Height to 10
Return a screenshot of the result

Design a Flange

Claude: Design a flange with outer diameter 100mm, inner diameter 50mm, and 6 bolt holes

The MCP server can execute complex Python code to create parametric designs.

Export Model

Claude: Export the current model to STEP format

Configuration

Environment Variables

FREECAD_HOST: Hostname/IP of FreeCAD RPC server (default: localhost)
FREECAD_PORT: Port of FreeCAD RPC server (default: 9000)
FREECAD_ONLY_TEXT: Set to true to disable image feedback and reduce API costs (default: false)

Network Configuration

If FreeCAD is running on a remote server:

export FREECAD_HOST=192.168.1.138
export FREECAD_PORT=9000

Or update docker-compose.yml to use external network.

Development

Project Structure

freecad-mcp/
├── src/
│   └── freecad_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       └── server.py          # MCP server implementation
├── freecad_rpc_server.py      # FreeCAD RPC server
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
└── README.md

Running Tests

pip install -e ".[dev]"
pytest

Code Formatting

black src/
ruff check src/

Troubleshooting

Connection Issues

Verify FreeCAD RPC server is running: docker logs your-freecad-container
Check network connectivity: docker network inspect freecad-network
Test RPC connection: curl http://localhost:9000

Image Feedback Issues

If images are not appearing in Claude Desktop:

Set FREECAD_ONLY_TEXT=true to disable images
Check FreeCAD GUI is properly initialized with Xvfb

Contributing

Contributions welcome! Please:

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

License

MIT License - see LICENSE file for details

Acknowledgments

Inspired by neka-nat/freecad-mcp

Twine2546/freecad-mcp