# CAD MCP Server

[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/protocol-MCP-8A2BE2.svg)](https://modelcontextprotocol.io)
[![Built with ezdxf](https://img.shields.io/badge/built%20with-ezdxf-orange.svg)](https://ezdxf.mozman.at/)
[![Formats: DXF · DWG](https://img.shields.io/badge/formats-DXF%20%C2%B7%20DWG-lightgrey.svg)](#dwg-support)

An [MCP](https://modelcontextprotocol.io) server that lets Claude (and any other
MCP client) **read, analyze, and edit CAD files** — both **DXF** and **DWG** —
powered by [`ezdxf`](https://ezdxf.mozman.at/).

It runs as a small local Python process over stdio. Your CAD files never leave
your machine.

- **DXF** — read and edit directly, no extra setup.
- **DWG** — Autodesk's proprietary binary format. `ezdxf` cannot parse it alone,
  so DWG is converted to DXF automatically via the free **ODA File Converter**
  ([one-time install](#dwg-support)). Once installed, DWG works everywhere DXF does.

---

## Quick start (easiest — no clone, no pip)

If you have [`uv`](https://docs.astral.sh/uv/) installed, you don't clone
anything or manage dependencies — `uvx` fetches and runs the server for you.

**Install `uv` once:**

```bash
# Windows (PowerShell):
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Then add the server in one line:**

```bash
# Claude Code:
claude mcp add cad -- uvx --from git+https://github.com/Codemod3/cad-mcp cad-mcp
```

For **Claude Desktop**, drop this into your config (see paths
[below](#claude-desktop)) — no clone, no paths to edit:

```json
{
  "mcpServers": {
    "cad": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Codemod3/cad-mcp", "cad-mcp"]
    }
  }
}
```

That's it. First run downloads deps automatically; later runs are instant.
Restart the client and the tools appear. (DWG still needs the free
[ODA File Converter](#dwg-support); DXF works immediately.)

Prefer to clone and manage Python yourself? See [Manual install](#manual-install).

---

## What it can do

### Read / analyze (never modifies files)

| Tool | What it does |
|---|---|
| `dxf_summary` | Overview — version, units, layers, entity counts, extents |
| `dxf_list_layers` | All layers with color, linetype, on/frozen/locked state |
| `dxf_get_layer_entities` | All entities on a specific layer |
| `dxf_get_entities_by_type` | Filter by type (LINE, CIRCLE, TEXT, …), optional layer filter |
| `dxf_get_text` | Extract all TEXT and MTEXT annotations |
| `dxf_get_dimensions` | Extract all DIMENSION annotations |
| `dxf_get_blocks` | List named block definitions |
| `dxf_get_block_detail` | Inspect entities inside a block |

### Edit (writes to a copy — your original is never touched)

| Tool | What it does |
|---|---|
| `cad_create_editable_copy` | Copy the original DXF/DWG to `<name>_edited.dxf`. **Run this first.** |
| `cad_add_line` | Draw a line |
| `cad_add_circle` | Draw a circle |
| `cad_add_arc` | Draw an arc |
| `cad_add_text` | Add a text label |
| `cad_add_polyline` | Draw connected segments (LWPOLYLINE), optionally closed |
| `cad_add_layer` | Create a layer |
| `cad_delete_entity` | Delete one entity by its handle |
| `cad_export_dwg` | Convert the edited `.dxf` back to `.dwg` (needs ODA File Converter) |

**Editing model — safe by design:**

1. Call `cad_create_editable_copy` on your original → it returns the copy's path.
2. Pass **that copy path** to every edit tool. Edits save in place and **stack**,
   so keep drawing on the same file.
3. Your original is **never** modified.
4. DWG can't be written directly, so edits always happen on the `.dxf` copy;
   run `cad_export_dwg` at the end if you need a `.dwg` back.

---

## Requirements

- **Python 3.10+** (only for the manual install; `uvx` handles this for you)
- The Python packages in `requirements.txt` (installed below)
- **DWG only:** the free [ODA File Converter](#dwg-support)

Check your Python:

```bash
python --version      # must be 3.10 or newer (try python3 on macOS/Linux)
```

---

## Manual install

Use this if you'd rather clone the repo and manage Python yourself.

### 1. Get the code

```bash
git clone https://github.com/Codemod3/cad-mcp.git
cd cad-mcp
```

### 2. Install dependencies

Recommended — use a virtual environment so nothing pollutes your system Python:

```bash
python -m venv .venv
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# macOS / Linux:
source .venv/bin/activate

pip install -r requirements.txt
```

Or install as a proper command (`cad-mcp`) via `pip`:

```bash
pip install .
```

### 3. Verify it runs

```bash
python server.py
```

It should print a startup line to stderr and then wait silently (it's listening
for an MCP client over stdio). Press `Ctrl+C` to stop. If you see no import
errors, you're ready to connect a client.

---

## Connect to a client

Point your MCP client at `server.py`. **Use the full absolute path** to the file,
and the same Python that has the dependencies installed.

### Claude Desktop

Edit the config file:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "cad": {
      "command": "python",
      "args": ["C:\\full\\path\\to\\cad-mcp\\server.py"]
    }
  }
}
```

> On macOS/Linux use `"python3"` and a `/full/path/to/cad-mcp/server.py`.
> If you used a virtualenv, point `command` at that venv's python, e.g.
> `C:\\path\\to\\cad-mcp\\.venv\\Scripts\\python.exe`.

Restart Claude Desktop. The CAD tools appear automatically.

### Claude Code (CLI)

**Easiest — no clone (needs `uv`):**

```bash
claude mcp add cad -- uvx --from git+https://github.com/Codemod3/cad-mcp cad-mcp
```

**If you cloned the repo instead:**

```bash
claude mcp add cad -- python "C:\full\path\to\cad-mcp\server.py"
```

**Scope (where the server is available):**

```bash
claude mcp add cad --scope user  -- uvx --from git+https://github.com/Codemod3/cad-mcp cad-mcp   # all your projects
claude mcp add cad --scope project -- uvx --from git+https://github.com/Codemod3/cad-mcp cad-mcp  # writes .mcp.json for teammates
```

The repo also ships a ready **`.mcp.json`** — run Claude Code inside the project
folder and the server loads automatically, no command needed.

Verify with `/mcp`, then just ask Claude to read or edit a CAD file. Remove with
`claude mcp remove cad`.

---

## DWG support

DWG files need the free **ODA File Converter** installed once:

1. Download for your OS: <https://www.opendesign.com/guestfiles/oda_file_converter>
2. Install it. Default Windows path:
   `C:\Program Files\ODA\ODAFileConverter <version>\ODAFileConverter.exe`
3. Ensure it's on your `PATH`, or leave it at the default location where `ezdxf`
   finds it automatically.

Then use `.dwg` files exactly like `.dxf` — conversion is automatic. If the
converter is missing, DWG tools return a clear error and **DXF keeps working**.

---

## Usage examples

Once connected, just talk to Claude:

- *"Summarize this DXF file: C:\drawings\floor_plan.dxf"*
- *"What layers are in site_plan.dwg?"*
- *"Extract all the text annotations from my drawing."*
- *"Make an editable copy of plan.dxf, then add a circle radius 5 at (10,10) on a new layer called NOTES."*
- *"Draw the outline of a 20×10 room as a closed polyline, then export it to DWG."*

---

## Supported entity types (read)

LINE, CIRCLE, ARC, LWPOLYLINE, TEXT, MTEXT, INSERT (block refs), DIMENSION,
LEADER, ELLIPSE, SPLINE — all other types are still captured with their common
attributes (layer, color, handle).

---

## Development

Run the test suite (offline, DXF only — no ODA converter needed):

```bash
pip install -r requirements.txt pytest pytest-asyncio
python -m pytest
```

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| Tools don't appear in the client | Use the **absolute** path to `server.py`; fully restart the client. |
| `ModuleNotFoundError: ezdxf` / `fastmcp` | The `command` python isn't the one with deps. Point it at your venv's python, or `pip install -r requirements.txt` for that interpreter. |
| DWG tools error about ODA | Install the [ODA File Converter](#dwg-support) and make sure it's on `PATH`. |
| "Cannot edit a .dwg file in place" | Expected — run `cad_create_editable_copy` first, edit the `.dxf` copy, then `cad_export_dwg`. |
| Client shows a broken/empty connection | Something printed to stdout. This server logs only to stderr; if you added prints, remove them — stdout is the MCP protocol channel. |

---

## License

MIT — see [LICENSE](LICENSE).