Skip to main content
Glama
AutoCAD MCP

AutoCAD MCP

README.md
# AutoCAD MCP Server

[![Version](https://img.shields.io/badge/Version-v0.5.0-blue.svg)](https://github.com/gabrielbsandim/autocad-mcp/releases)
[![MCP Protocol](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-6B46C1.svg)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/Python-3.11+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/Platforms-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)]()
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

A local Model Context Protocol (MCP) server that connects **Claude** (Claude Desktop, Claude Code, Antigravity, Cursor) directly to CAD drawings. Query geometry, automate drawing routines, check layer conventions, and generate architectural schedules through plain-language prompts.

---

## Two Operating Modes

```
               ┌────────────────────────────────────────────────────────┐
               │              Claude (MCP Host Client)                  │
               └───────────────────────────┬────────────────────────────┘
                                           │ stdio (JSON-RPC)
                                           ▼
               ┌────────────────────────────────────────────────────────┐
               │                   AutoCAD MCP Server                   │
               └───────────────┬────────────────────────┬───────────────┘
                               │                        │
       [Windows COM Interface] │                        │ [Headless ezdxf Engine]
                               ▼                        ▼
               ┌────────────────────────┐      ┌────────────────────────┐
               │   Live CAD Execution   │      │   Headless File Mode   │
               │  • AutoCAD (Full)      │      │  • Windows, macOS, Lin │
               │  • BricsCAD            │      │  • Direct .dxf editing │
               │  • ZWCAD / GstarCAD    │      │  • .dwg via ODA Conv.  │
               │  • Interactive undo    │      │  • In-memory sandbox   │
               └────────────────────────┘      └────────────────────────┘
```

1. **Live CAD Mode (Windows):** Connects directly to the active drawing inside AutoCAD (not LT), BricsCAD, ZWCAD, or GstarCAD via Windows COM. Supports live viewport selections and instant visual updates with atomic undo (`U`).
2. **Headless File Mode (Cross-Platform — Windows, macOS, Linux):** Inspects and edits `.dxf` files directly using pure Python (`ezdxf`), and `.dwg` files when the free [ODA File Converter](https://www.opendesign.com/guestfiles/oda_file_converter) is installed. No CAD license or software required.

---

## Quickstart & Installation

### Option 1: Claude Desktop (Windows & macOS)

1. Download the pre-built `autocad-mcp-<version>.mcpb` bundle from the [latest release](https://github.com/gabrielbsandim/autocad-mcp/releases/latest).
2. Double-click the file to install into Claude Desktop.
3. Requires [uv](https://docs.astral.sh/uv/) installed (handles Python runtime automatically).

### Option 2: Claude Code

```bash
/plugin install autocad --marketplace gabrielbsandim/autocad-mcp
```

### Option 3: Manual MCP Configuration

For Claude Desktop, Cursor, or Windsurf, configure the server in your MCP configuration file:

```json
{
  "mcpServers": {
    "autocad": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\path\\to\\autocad-mcp", "--no-dev", "autocad-mcp"],
      "env": {
        "AUTOCAD_MCP_LAYER_STANDARD": "asbea",
        "AUTOCAD_MCP_LOCALE": "pt-BR"
      }
    }
  }
}
```

---

## Natural Language Prompts

Talk to CAD naturally:

- *"Which drawing is currently open and what are its drawing units?"*
- *"Generate the area schedule for all rooms and place the table beside the floor plan."*
- *"Monte o quadro de esquadrias com largura, altura e peitoril das portas e janelas."*
- *"Confira as áreas do terreno contra os parâmetros da lei de zoneamento: TO 60%, CA 2.0 e TP 15%."*
- *"Export all layouts to PDF using their individual page setups."*
- *"Standardize all layers according to AsBEA conventions."*
- *"Draw a 4.00 x 3.50 m room with 15 cm thick walls starting at origin (0,0)."*

---

## Complete Tools Reference (23 Tools)

| Category | Tools | Description |
| :--- | :--- | :--- |
| **Drawing & Session** | `status`, `open_drawing`, `save_drawing`, `undo`, `set_variable` | Inspect active drawing, open read-only by default, atomic single-step undo, inspect/set safe system variables. |
| **Query & Inspection** | `describe_drawing`, `find_entities` | Summarize layers, blocks, and sheets; search entities by type, layer, bounding region, text content, handle, or active viewport selection. |
| **Drawing Generation** | `draw` | Draw lines, polylines, rectangles, circles, arcs, text, dimensions, hatches, and **walls from centerline** in batch. |
| **Transform & Edit** | `transform`, `delete_entities`, `change_properties` | Move, copy in series, rotate, scale, mirror, offset, and modify entity attributes. |
| **Layer Management** | `manage_layer`, `merge_layers`, `check_layer_standard`, `apply_layer_standard` | Create/modify layers; automatically audit and remap legacy layers to **AsBEA** or **AIA** standards using aliases. |
| **Areas & Quantities** | `room_areas`, `label_rooms`, `takeoff`, `site_areas`, `place_table`, `export_csv` | Calculate room areas and place tags; door & window schedule; site coverage indices (**TO, CA, TP**); render native CAD tables or export Excel-safe CSVs. |
| **Output & Maintenance** | `export_pdf`, `maintain_drawing` | Batch export sheets/layouts to PDF with configured plot styles; run purge and audit diagnostics. |

---

## Built for Architectural Standards

### Brazilian Architectural Practice (AsBEA)
- **Quadro de Áreas:** Automatic boundary discovery with room tags (`A = 12,50 m²`) centered within irregular or L-shaped rooms.
- **Quadro de Esquadrias:** Automatically groups doors and windows by schedule code, reading width, height, and sill from attributes or physical block boundaries.
- **Índices Urbanísticos:** Calculates lot coverage (Taxa de Ocupação - TO), floor area ratio (Coeficiente de Aproveitamento - CA), and permeable area (Taxa de Permeabilidade - TP) against municipal zoning limits.
- **Localized Formatting:** Default headers and CSV delimiters format numbers as `1.234,50` with semicolons for zero-friction Excel compatibility (`pt-BR`). Switchable to `en-US` via `AUTOCAD_MCP_LOCALE`.

---

## Security & Reliability Guardrails

- **Zero Network Traffic:** The server communicates exclusively via local stdio. It opens no network sockets and transmits no telemetry.
- **Strict Read-Only Default:** Opening files is read-only by default; files are never overwritten without explicit `overwrite=True`.
- **Directory Jail:** `AUTOCAD_MCP_ALLOWED_DIRS` strictly confines all read/write paths, blocking network shares or unauthorized file exploration.
- **Atomic Undo Rollbacks:** Multi-step drawing operations are grouped into a single undo transaction. If an error occurs halfway through, changes are automatically rolled back.
- **No Arbitrary Scripts:** Does not execute unvetted AutoLISP or arbitrary shell commands.

### Environment Configuration

| Variable | Default | Purpose |
| :--- | :--- | :--- |
| `AUTOCAD_MCP_READONLY` | `0` | Set `1` to lock server into read-only mode (no writes/saves allowed). |
| `AUTOCAD_MCP_LAYER_STANDARD` | `aia` | Built-in standard (`asbea` or `aia`) or custom JSON mapping path. |
| `AUTOCAD_MCP_LOCALE` | `pt-BR` | Number and table formatting: `pt-BR` (`1.234,50`) or `en-US` (`1,234.50`). |
| `AUTOCAD_MCP_ALLOWED_DIRS` | `""` | Delimited list of authorized directories for file I/O. |
| `AUTOCAD_MCP_BACKEND` | `auto` | Backend mode: `auto`, `com` (Windows live CAD), or `file` (ezdxf). |
| `AUTOCAD_MCP_TIMEOUT` | `60` | Maximum seconds to wait for a busy CAD application before timing out. |

---

## Development & Testing

```bash
# Install development dependencies with uv
uv sync --extra dev --extra pdf

# Run end-to-end integration test suite against real DXF test fixtures
uv run pytest

# Verify stdio communication loop
uv run python scripts/stdio_check.py

# Live CAD verification (Windows with CAD open)
uv run python scripts/live_check.py
```

---

## License

[MIT](LICENSE) © Gabriel Sandim