![FreeCAD MCP by staf_37](docs/assets/freecad-mcp-staf_37.png)

# FreeCAD MCP by staf_37

[English](README.md) · [Русский](docs/README.ru.md) · [简体中文](docs/README.zh-CN.md) · [Español](docs/README.es.md) · [हिन्दी](docs/README.hi.md) · [العربية](docs/README.ar.md) · [日本語](docs/README.ja.md)

[![Stars](docs/badges/stars.svg)](https://github.com/Mizzzord/FreeCAD-MCP-by-staf_37/stargazers)
[![Forks](docs/badges/forks.svg)](https://github.com/Mizzzord/FreeCAD-MCP-by-staf_37/forks)
[![Issues](docs/badges/issues.svg)](https://github.com/Mizzzord/FreeCAD-MCP-by-staf_37/issues)
[![Release](docs/badges/release.svg)](https://github.com/Mizzzord/FreeCAD-MCP-by-staf_37/releases)
[![Downloads](docs/badges/downloads.svg)](https://github.com/Mizzzord/FreeCAD-MCP-by-staf_37/releases)
[![Build](docs/badges/build.svg)](https://github.com/Mizzzord/FreeCAD-MCP-by-staf_37/actions/workflows/build.yml)
![32 MCP tools](docs/badges/tools.svg)
![Seven documentation languages](docs/badges/languages.svg)

**Create CAD models and drawings in your installed FreeCAD, directly from your AI workspace.**
Connect Codex, Claude Code, Cursor, VS Code or another local MCP client. Maintained by [staf_37](https://github.com/Mizzzord).

[Download applications](#download-applications) · [Installation](docs/installation.md) · [Tools](docs/tools.md) · [Troubleshooting](docs/installation.md#troubleshooting) · [Contributing](CONTRIBUTING.md)

## Download → open → connect

1. Install **FreeCAD with its graphical interface** separately.
2. Download the application archive for your operating system from the table below. You do **not** need the repository, a compiler or a separate Python installation.
3. Extract the **entire archive**. Open `FreeCAD-MCP.app` on macOS, `FreeCAD-MCP.exe` on Windows, or `FreeCAD-MCP` on Linux.
4. Check the detected FreeCAD path, select your clients and press **Connect / Подключить**.
5. Restart the selected clients and approve the MCP server if they request trust.

The application copies its runtime into your user directory. After successful setup, the extracted download folder can be moved or removed. Keep the complete folder until setup finishes. If FreeCAD is not detected, select its GUI executable or `.app` manually.

> This repository is private. Downloads require a GitHub account with access. The app interface currently uses Russian and English; the guides are available in seven languages.

## What you can do

| Workflow | Capabilities |
|---|---|
| Models | Create documents, objects, sketches, constraints, Pad/Pocket and boolean operations |
| Editing | Change properties and expressions, recompute, inspect geometry, Undo/Redo |
| Drawings | Create TechDraw pages, projected views and dimensions |
| Files | Save FCStd; export STEP, IGES, BREP, meshes, SVG and PDF as supported by the relevant tools |
| View | Change the camera, select geometry and return actual FreeCAD screenshots |
| Advanced | Explore installed workbenches and call FreeCAD's Python API |

Example request to your agent:

> In a new FreeCAD document, create a 60 × 40 × 12 mm plate with a central Ø12 mm hole. Make a drawing with front, side and top views. Save FCStd, STEP and PDF in my chosen folder. Preserve existing documents.

## Local by design

```mermaid
flowchart LR
    A[AI client] -->|MCP stdio| B[FreeCAD MCP]
    B -->|Authenticated loopback TCP| C[Bridge queue]
    C -->|GUI thread| D[FreeCAD models and drawings]
```

FreeCAD itself reports the correct profile directory. The installer adds the bridge there and keeps its own components in a stable user directory. With auto-start enabled, FreeCAD opens when the agent first calls a CAD tool. Starting FreeCAD can take longer than starting the MCP server.

The bridge listens only on `127.0.0.1` and requires a random session token. Python commands run with FreeCAD's privileges: this is **not a sandbox**. Cloud agents without access to your computer cannot directly use this local stdio server. See [security](SECURITY.md).

## Clients and platform limits

Codex, Claude Code, Cursor and the default VS Code user profile have automatic configuration. Other local MCP clients can import the generated `manual-config.json`. Existing configuration is backed up; other servers and custom environment values are preserved. JSONC files and nonstandard client profiles may require the client's own Add Server interface.

Targets: Windows x64, Linux x64, macOS Apple Silicon and Intel. Linux requires a compatible glibc desktop distribution, such as Ubuntu 22.04 or newer. Sandboxed FreeCAD packages, WSL-to-Windows connections, headless FreeCADCmd and mobile operating systems are outside automatic setup support.

Packaged startup/MCP checks are separate from real CAD verification. The complete FreeCAD 1.1.3 CAD workflow has been verified on macOS arm64. See [validation](docs/validation.md) and the linked build run for the actual platform checks. Binaries are not commercially signed or notarized; your OS may ask you to approve opening them.

## Documentation and development

- [Installation, updates, removal and troubleshooting](docs/installation.md)
- [Russian installation reference](docs/installation.ru.md)
- [Tool reference and CAD examples — Russian](docs/tools.md)
- [Architecture — Russian](docs/architecture.md)
- [Validation record — Russian](docs/validation.md)
- [Release and packaging guide](docs/releases.md)
- [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)

For development, use Python 3.11+ and `uv`:

```sh
uv sync --locked --group build
uv run pytest -q
uv run --group build python scripts/build_app.py
```

Repository statistics are a snapshot, not a live external counter. [Last refresh and values](docs/badges/stats.json). Maintainers can refresh them with `python scripts/update_badges.py` using their existing GitHub CLI authentication. No token is embedded in the badges.

## Download applications

**v0.2.2** — complete application bundles with Python and dependencies included. Download the bundle for your CPU architecture; do not select GitHub's “Source code” archives unless you want to develop the project.

| Platform | Direct download | Open after extraction |
|---|---|---|
| Windows x64 | [Windows ZIP](https://github.com/Mizzzord/FreeCAD-MCP-by-staf_37/releases/download/v0.2.2/FreeCAD-MCP-windows-x64.zip) | `FreeCAD-MCP/FreeCAD-MCP.exe` |
| Linux x64 | [Linux TAR.GZ](https://github.com/Mizzzord/FreeCAD-MCP-by-staf_37/releases/download/v0.2.2/FreeCAD-MCP-linux-x64.tar.gz) | `FreeCAD-MCP/FreeCAD-MCP` |
| macOS Apple Silicon | [macOS ARM64 ZIP](https://github.com/Mizzzord/FreeCAD-MCP-by-staf_37/releases/download/v0.2.2/FreeCAD-MCP-macos-arm64.zip) | `FreeCAD-MCP.app` |
| macOS Intel | [macOS x64 ZIP](https://github.com/Mizzzord/FreeCAD-MCP-by-staf_37/releases/download/v0.2.2/FreeCAD-MCP-macos-x64.zip) | `FreeCAD-MCP.app` |

[Release notes and all assets](https://github.com/Mizzzord/FreeCAD-MCP-by-staf_37/releases/tag/v0.2.2) · [SHA-256 checksums](https://github.com/Mizzzord/FreeCAD-MCP-by-staf_37/releases/download/v0.2.2/SHA256SUMS.txt)