# AutoCAD MCP

An MCP (Model Context Protocol) server that lets an AI assistant draw and
inspect AutoCAD drawings — either headlessly (no AutoCAD installation needed)
or by driving a live AutoCAD session on Windows.

**Author:** Sachin Dev
[github.com/sachinsapkotadev](https://github.com/sachinsapkotadev) ·
[github.com/sapkotasachin064-beep](https://github.com/sapkotasachin064-beep)

## Two engines, one API

Every tool works the same way regardless of which engine is active — the
engine is chosen once, at startup, via `AUTOCAD_MCP_BACKEND`:

| | `ezdxf` (headless) | `com` (live AutoCAD) |
|---|---|---|
| Requires | nothing (pure Python) | Windows + full AutoCAD (not LT) + `pywin32` |
| Reads/writes | `.dxf` | `.dwg` (and `.dxf` on open) |
| Good for | CI, servers, no AutoCAD license | working in your actual AutoCAD session |

`AUTOCAD_MCP_BACKEND=auto` (the default) picks `com` if a running AutoCAD
instance can be reached on Windows, else falls back to `ezdxf`. In `auto`
mode this is re-checked on every tool call for as long as the server is
still on `ezdxf`: if AutoCAD was not reachable when the server started but
gets launched later, the next tool call switches over to live AutoCAD
instead of silently staying on the headless fallback for the rest of the
process. Once upgraded to `com` it never downgrades automatically — use
`autocad_connection_status` to check which backend is actually active before
drawing.

## Install

```bash
pip install -e .                 # headless (ezdxf) only
pip install -e ".[com]"          # + live AutoCAD support (Windows)
pip install -e ".[preview]"      # + autocad_render_preview on the ezdxf backend
pip install -e ".[com,preview,dev]"  # everything, plus the test suite
```

Register it with your MCP client (Claude Desktop, Cursor, etc.) to run:

```bash
sachindev-autocad-mcp                       # stdio transport (default)
sachindev-autocad-mcp --transport streamable-http --port 8000
```

## Configuration

| Environment variable | Default | Effect |
|---|---|---|
| `AUTOCAD_MCP_BACKEND` | `auto` | `auto` \| `ezdxf` \| `com` |
| `AUTOCAD_MCP_WORKSPACE` | unset | Confines every file-path argument (open/save, block import, preview output) to this directory tree. Unset = unrestricted. |
| `AUTOCAD_MCP_ALLOW_RAW_COMMANDS` | unset | Must be `1` to enable `autocad_send_command` (raw AutoCAD command-line / AutoLISP on a live session). A guardrail, not a sandbox — read the tool's docstring before enabling it. |

## What you get

**Documents** — new/open/save, document info (units, layers, entity count, extents).

**Connection & drawing initialization** — `autocad_connection_status` (which
backend is active, whether live AutoCAD is reachable, never launches it).
`autocad_set_drawing_units` applies and verifies the Drawing Units dialog
settings (length/angle type & precision, angle direction, insertion scale,
lighting units) — defaults to an Engineering template (Engineering length at
0.000" precision, Decimal Degrees, counter-clockwise, Inches, International
lighting). `autocad_create_boundary` creates (or idempotently reuses) a
rectangular/circular/polyline sheet boundary on the `SHEET_BOUNDARY` layer,
reserving an optional annotation margin and reporting usable extents/area.
`autocad_check_fits_boundary` checks whether proposed geometry fits inside
that usable area without ever resizing it. `autocad_initialize_drawing`
composes the units + boundary steps into one idempotent call.

**Layers** — create/list/delete, freeze/thaw, lock/unlock, on/off, set current.

**Entities** — line, polyline, circle, arc, text; query (filtered, paginated),
get, delete (single and bulk).

**Transforms** — move, copy, rotate, scale, mirror, linear array, polar array.
Work on any entity type via its handle.

**Hatch** — filled region from a boundary point list (solid or named pattern).

**Dimensions** — aligned, angular, radius/diameter.

**Blocks** — insert by name or by importing an external `.dxf`/`.dwg` file,
read/set block attributes.

**Architectural workflow tools** — `autocad_draw_wall` (centerline → two
parallel faces + end caps), `autocad_draw_room` (rectangular room with inner/
outer wall loops + area label), `autocad_add_door` (leaf + swing arc).

**Live-session extras (COM backend only)** — `autocad_undo`,
`autocad_send_command` (gated, see above), `autocad_render_preview` (window
screenshot). On the `ezdxf` backend, `autocad_render_preview` instead renders
the drawing headlessly via matplotlib — no AutoCAD required.

Every tool returns JSON. Failures come back as a string starting with
`"Error (<ExceptionType>): ..."` rather than raising, so a client always gets
a readable result.

## Using it from an AI client

This server speaks plain MCP over stdio — any MCP client that can launch a
local command can use it, with no per-client code in this project. The
client supplies the AI model; this server never calls one itself and never
needs model-provider credentials.

**OpenCode** (`~/.config/opencode/opencode.json` or
`C:\Users\<you>\.config\opencode\opencode.json`):

```json
{
  "mcp": {
    "servers": {
      "autocad": {
        "type": "local",
        "command": ["C:\\path\\to\\Autocad MCP\\.venv\\Scripts\\python.exe", "-m", "sachindev_autocad_mcp"],
        "enabled": true
      }
    }
  }
}
```

Use the absolute path to the project's own venv `python.exe` (not a global
Python) so the right dependencies (`pywin32`, `ezdxf`) are on the path.

**Compatibility matrix** — status reflects what was actually verified, not
assumed from "it supports MCP":

| Client | Status |
|---|---|
| OpenCode | Config added to this machine's `opencode.json` and validated (valid JSON, exact command launches); not exercised through an actual OpenCode chat session |
| Claude Desktop | Configuration documented, not tested — add under `mcpServers` in `claude_desktop_config.json` |
| Claude Code (this CLI) | Configuration documented, not tested — `claude mcp add` or project `.mcp.json` |
| Cursor | Configuration documented, not tested — `.cursor/mcp.json` |
| VS Code (MCP/Copilot Chat) | Configuration documented, not tested — `.vscode/mcp.json` |
| Cline / Roo Code | Configuration documented, not tested — each has its own MCP settings JSON |
| Continue | Configuration documented, not tested — `mcpServers` in `config.yaml` |
| Windsurf | Configuration documented, not tested — `mcp_config.json` |
| Zed | Configuration documented, not tested — uses `context_servers`, not `mcpServers` |
| OpenAI Codex CLI | Configuration documented, not tested — `mcp_servers` table in `~/.codex/config.toml` |
| Google Gemini CLI | Configuration documented, not tested — `mcpServers` in `~/.gemini/settings.json` |
| Aider | Research required — MCP support is new/limited as of this writing; verify current docs |
| Goose | Research required — supports MCP as "extensions"; exact current config format not verified here |
| Amazon Q Developer | Research required |
| JetBrains AI Assistant | Research required |
| Google Antigravity | Research required |
| ChatGPT desktop | Research required — its MCP/connector support has historically targeted remote/hosted servers, not arbitrary local stdio processes; verify before assuming this server can be used from it |
| Gemini API / AI Studio, raw model APIs | Not applicable — these are model providers, not MCP clients; use them through an MCP-capable client or agent framework, which then talks to this server |

A provider's API being OpenAI-compatible does not mean a given client can
reuse another client's subscription or login — authentication is set by
each client independently.

## Development

```bash
pip install -e ".[com,preview,dev]"
pytest
```

The test suite runs entirely against the `ezdxf` backend (no AutoCAD or
Windows required) and covers the geometry helpers, input validation, the
workspace path sandbox, and every backend method.

## License

MIT — see [LICENSE](LICENSE).