AutoCAD LT AutoLISP MCP Server
# AutoCAD MCP Server
## PuranOS role and current scope
This is an active drawing-automation integration used alongside the PuranOS engineering workflow. AutoCAD LT and headless DXF are distinct backends with the platform requirements below. The current guarded revision helpers operate on an explicitly identified working drawing; engineering basis, canonical equipment records and release decisions live in the wider workflow.
[Sizing-to-balance, proposals and BEPs](https://github.com/puran-water/PuranOS-public/blob/main/docs/workflows.md) produce the engineering basis. [PuranOS Studio](https://github.com/puran-water/PuranOS-public/blob/main/docs/studio.md) presents retained review publications. Neither a successful CAD command nor a screenshot approves a design. This repository is maintained separately from the six-server public calculation mirror.
Built by [Puran Water](https://puranwater.com/) · [Discuss engineering or a drawing workflow](https://puranwater.com/contact/).
MCP server for AutoCAD LT automation and headless DXF generation.
Two backends, one API:
| Backend | Runtime | Requires AutoCAD? | Screenshot |
|---------|---------|-------------------|------------|
| **File IPC** | Windows Python | Yes — AutoCAD LT 2024+ (Windows) | Win32 PrintWindow |
| **ezdxf** | Any platform | No (headless) | matplotlib render |
The server exposes **8 consolidated tools** (`drawing`, `entity`, `layer`, `block`, `annotation`, `pid`, `view`, `system`) over the MCP stdio transport. An MCP client (Claude Desktop, Claude Code, etc.) connects and drives AutoCAD through natural-language requests.
## Prerequisites (File IPC backend)
- **Windows 10/11** (the File IPC backend uses Win32 APIs for focus-free window messaging)
- **AutoCAD LT 2024 or newer** — AutoLISP support was added in LT 2024 for Windows. AutoCAD LT for Mac exists but does **not** support AutoLISP.
- **Python 3.10+** (Windows native — not WSL Python)
- **uv** package manager ([install guide](https://docs.astral.sh/uv/getting-started/installation/))
> The ezdxf headless backend works on any platform (Linux, macOS, WSL) for offline DXF generation without AutoCAD installed.
## Quick Start
### 1. Clone and install
```powershell
git clone https://github.com/puran-water/autocad-mcp.git
cd autocad-mcp
uv sync
```
### 2. Use an isolated document job
The native backend uses a resident AutoLISP file queue. It does not type each command
or steal foreground focus. Load the Python and Lisp files from the same
build; `system.runtime` reports the exact loaded/disk hashes and qualification.
A build without a matching `native-qualification.json` reports `different_build` or
`unqualified`: qualify it on a disposable drawing ([queue workflow](docs/queue-workflow.md))
before production use. Automatic document switching and DXF transitions are not supported.
From WSL, `scripts/run-native-wsl.py` starts
`%USERPROFILE%\mcp-servers\autocad-mcp\run-native-ready.cmd`, which calls a
`run-native.cmd` you place beside it to start the Windows server.
Start MCP first, then use `system` with `operation="job"`:
```json
{"action":"launch","drawing":"C:/work/revision.dwg",
"ipc_dir":"C:/work/ipc-job-001",
"executable":"C:/Program Files/Autodesk/AutoCAD LT 2027/acadlt.exe"}
```
The drawing must be an existing writable working copy, not already open. The IPC
directory must be new. The launcher starts a separate process with a startup script;
it never switches documents in an AutoCAD process you already have open. Poll `action="observe"`
with `path="<ipc_dir>/job.json"`, then `action="attach"` when the native
worker is idle. The record is `<ipc_dir>/job.json`. A second MCP process can explicitly
attach to this same job after a server restart. Do not launch a second copy on timeout.
Missing fonts or other startup dialogs are reported for deliberate resolution.
For a drawing already open in your own session, `system.worker prepare` can produce a one-use
bootstrap SCRIPT. This is a deliberate handoff, not an automatic keyboard fallback.
Keep one authoritative working DWG and reconcile unsaved changes before choosing
between an existing document and a new process.
### 3. Configure your MCP client
Add to your MCP client configuration (e.g. Claude Desktop `claude_desktop_config.json`):
```json
{
"mcpServers": {
"autocad-mcp": {
"command": "C:\\path\\to\\autocad-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "autocad_mcp"],
"env": { "AUTOCAD_MCP_BACKEND": "file_ipc" }
}
}
}
```
**Key points:**
- The `command` must point to the **Windows Python** inside the project venv (not WSL python).
- `AUTOCAD_MCP_BACKEND` can be `auto` (default — tries File IPC, falls back to ezdxf), `file_ipc` (requires AutoCAD), or `ezdxf` (headless only).
#### Running from WSL
If your MCP client runs in WSL (e.g. Claude Code), launch the server through `cmd.exe` so it runs as a native Windows process:
```json
{
"mcpServers": {
"autocad-mcp": {
"type": "stdio",
"command": "cmd.exe",
"args": ["/d", "/s", "/c", "cd /d C:\\path\\to\\autocad-mcp && set AUTOCAD_MCP_BACKEND=file_ipc&& .venv\\Scripts\\python.exe -m autocad_mcp"]
}
}
}
```
### 4. Verify
From your MCP client, call:
```
system(operation="status")
```
You should see `backend: "file_ipc"` if AutoCAD is running, or `backend: "ezdxf"` for headless mode.
For native DWG work, require `file_ipc`; the examples above disable headless fallback.
Verify `DWGNAME`, `DWGPREFIX`, `CTAB` and `DBMOD` with `drawing.get_variables`, then
inspect a screenshot before editing. `status` alone does not identify the active DWG.
Use a Windows-local working copy if Windows cannot access a WSL UNC path, and copy
saved deliverables back explicitly. Never use `drawing.create` to make a working copy:
it erases and purges the active drawing.
## Journaled native revisions
`system(operation="revision", data={"action": "read", "drawing": "C:/work/copy.dwg",
"handles": ["ABCD"]})` reads native entities. The revision adapter supports bounded
exports, layout frames, guarded edits, plotting and AutoCAD 2010 saves. Each mutation
batch has 1–7 operations, a unique journal path, expected document identity and old
entity values. Receipts retain before/after state and created handles. Read the
[operation reference and recovery procedure](docs-revision.md) before use.
Revision clouds can follow an orthogonal route instead of enclosing unrelated labels:
```json
{
"action": "batch",
"drawing": "C:/work/copy.dwg",
"id": "route-cloud-01",
"journal": "C:/work/route-cloud-01.json",
"operations": [{
"kind": "cloud", "item": "approved-change-42",
"space": "Model", "layer": "REV-01",
"points": [[0,0], [8,0], [8,2], [2,2], [2,8], [0,8]],
"arc": 0.4, "text_height": 0.3, "revision": "01",
"marker_position": [10,3]
}]
}
```
Create the revision layer first. Pass this object to `system` with `operation="revision"`.
For the Windows CLI, save the object as `request.json` (the extra `action` is ignored):
```powershell
python -m autocad_mcp.revision batch request.json --output receipt.json
```
An existing MCP session can use the updated helper through `execute_lisp` without
acquiring a new tool schema: replace `action` with `operation` in the request, then
compile on WSL and submit the resulting expression as `data.code`:
```bash
python -m autocad_mcp.revision compile request.json \
--lisp-path C:/path/to/autocad-mcp/lisp-code/revision_tools.lsp --output batch.lsp
```
Keep the Python compiler and Windows LISP helper at the same repository revision.
In worker mode, `revision.save` and `drawing.save` preserve the existing on-disk DWG
format by default (AC1024, AC1027 or AC1032); an explicit format is verified afterward.
`revision.checkpoint` takes a new `path`, saves in place, then atomically copies and
hashes the saved bytes without changing the active document. Existing recovery files
are never overwritten. A copy error after a successful save reports that distinction.
Explicit Save As uses a guarded same-document worker handoff; automatic OPEN and DXF
transitions remain disabled. Do not infer their safety from a successful save.
Guarded revision patches can set an entity's linetype (DXF 6) and linetype scale
(DXF 48), for example electrical signal lines in a P&ID. The linetype must already
be loaded, or be ByLayer/ByBlock; the scale must be finite and positive. Old-value
checks apply to both fields. Inspect the native pattern at the intended plot scale.
For repeated instrument labels, an `attributes` operation updates up to 16 attributes
on one existing block. Supply the changed `attributes` and their `expected_attributes`;
native preflight checks unique tags, old values and unlocked layers before the batch
starts. This groups function/loop/alarm changes while retaining the seven-operation
batch limit, before/after receipts and screenshot review. It does not infer loop identities.
Use the guarded `rotate` revision operation to turn an existing planar block and its
attributes together about its insertion point. `target` is an absolute angle in radians;
include the expected insertion point (DXF 10), rotation (50) and normal (210), in addition
to type, owner and layer. This supports upright instrument lettering without recreating
each attribute. Recheck process/signal attachments: arbitrary equipment rotation can move
its ports. Old-value failures now identify the handle, DXF field and conflicting values.
Inspect native readback and a screenshot after every batch; save checkpoints between
sheets. Journals are evidence, not automatic rollback. Serialize desktop clients and
human edits. On timeout, reconcile the pending receipt and actual drawing before any
retry; newer clients hold dispatch until explicit acknowledgement. Older running
clients need reconnecting to acquire the process lease and new operation schema.
### Consistent symbols, crossing gaps and layers
`autocad_mcp.symbol_normalization.scale_with_connections(symbol, entities, target,
ports, item=..., anchor=...)` plans a bounded resize from qualified block-local XY
ports. It preserves rotation and mirror signs, matches LINE/open straight-polyline
endpoints, and refuses a resize that would turn an orthogonal connection diagonal.
The optional local anchor keeps that point fixed and retains attribute lettering
through a transform patch. Review unmatched ports, junctions and lettering yourself;
the planner does not infer equipment families or reroute a network. Its return value
contains `operations` and the before/after port matches. Supply fresh native entities.
For CTO symbols, inspect the installed DWG definition's units, base point and real
process ports before choosing target scale. Equal insertion factors across unrelated
definitions are not equal visible sizes. Keep proprietary CTO artwork outside this
repository. Normalize legend samples with the adopted symbol families.
`spline-gap` removes a short, explicitly selected interior interval of an open SPLINE.
Supply its full `expected_dxf` and two ordered 3D `gap` points on the curve. The helper
uses `command-s` inside the guarded call and verifies both resulting spline endpoints.
Use this for an embedded crossing jumper only after identifying the true crossing;
retain hose curvature elsewhere. A non-erase batch operation returning no handles now
fails with `MUTATION_RETURNED_NO_HANDLES` rather than claiming an empty success.
`rename_layers` accepts `drawing`, a new `journal` path, and 1–7 `pairs` of old/new
names. It preflights all names, preserves layer objects, compares all recorded layer
properties except name/ename, and records each rename. It does not merge layers or
change entity overrides. Update cached entity layers before planning another edit.
Layer `0` and `Defpoints` are reserved. Example compiler request:
```json
{"operation":"rename_layers","drawing":"C:/work/copy.dwg",
"journal":"C:/work/layers-01.json","pairs":[["Process","P-PIPE-MAIN"]]}
```
These operations were used in a native AutoCAD LT 2027 P&ID revision with bounded
readback and viewport review; no automated test suite was run for this change.
Refresh the actual view after a zoom before capturing it: `ZoomCenter` using the
current `VIEWCTR`/`VIEWSIZE` resolved stale screenshot frames where Regen alone did
not. Cloud replacement must account for the boundary, triangle and revision text
handles returned by its receipt.
The reusable `expected_state` helper preserves the first DXF value when codes repeat.
`cloud_covers_bounds` checks an entire target rectangle against a cloud polygon,
including its concave cutouts; bounding-box overlap alone is insufficient.
For layer cleanup or matching new piping to an existing run, a guarded `patch` can
set colour (DXF 62), layer (8), and lineweight (370). Include their actual old values
in `expect`; use `null` only when the native DXF group is absent. For example,
`"set": {"62": 221, "370": 13}` sets colour 221 and 0.13 mm lineweight. Read the
source run and its layer first: assigning ByLayer can change the plotted appearance.
The adapter validates the standard lineweight values, but does not decide the
engineering role, crossing priority, plot-style overrides or approved house weights.
## Tools
### `drawing` — File/drawing management
| Operation | Description | File IPC | ezdxf |
|-----------|-------------|----------|-------|
| `create` | Reset to clean drawing (erase all + purge) | Yes | Yes |
| `open` | Open an existing drawing | Yes | Yes (DXF) |
| `info` | Get entity count and layers | Yes | Yes |
| `save` | Save current drawing (to path if given) | Yes | Yes |
| `save_as_dxf` | Export as DXF | Yes | Yes |
| `plot_pdf` | Plot to PDF | Yes | No |
| `purge` | Purge unused objects | Yes | Yes |
| `get_variables` | Get system variables by name | Yes | Yes |
| `undo` | Undo last operation | Yes | No |
| `redo` | Redo last undone operation | Yes | No |
### `entity` — Entity CRUD + modification
**Create:** `create_line`, `create_circle`, `create_polyline`, `create_rectangle`, `create_arc`, `create_ellipse`, `create_mtext`, `create_hatch`
**Read:** `list`, `count`, `get`
**Modify:** `copy`, `move`, `rotate`, `scale`, `mirror`, `offset`\*, `array`, `fillet`\*, `chamfer`\*, `erase`
> \* `offset`, `fillet`, `chamfer` are File IPC only (not supported in ezdxf headless backend).
### `layer` — Layer management
`list`, `create`, `set_current`, `set_properties`, `freeze`, `thaw`, `lock`, `unlock`
### `block` — Block operations
| Operation | File IPC | ezdxf |
|-----------|----------|-------|
| `list` | Yes | Yes |
| `insert` | Yes | Yes |
| `insert_with_attributes` | Yes | Yes |
| `get_attributes` | Yes | Yes |
| `update_attribute` | Yes | Yes |
| `define` | No | Yes |
### `annotation` — Text, dimensions, leaders
`create_text`, `create_dimension_linear`, `create_dimension_aligned`, `create_dimension_angular`, `create_dimension_radius`, `create_leader`
### `pid` — P&ID operations (CTO symbol library)
`setup_layers`, `insert_symbol`, `list_symbols`, `draw_process_line`, `connect_equipment`, `add_flow_arrow`, `add_equipment_tag`, `add_line_number`, `insert_valve`, `insert_instrument`, `insert_pump`, `insert_tank`
> P&ID symbol insertion requires the [CAD Tools Online](https://www.cadtoolsonline.com/) (CTO) P&ID Symbol Library installed at `C:\PIDv4-CTO\`. The ezdxf backend has built-in CTO library support. For the File IPC backend, some P&ID operations require additional LISP helpers — see the P&ID section in the wiki for setup details.
### `view` — Viewport and screenshot
| Operation | Description |
|-----------|-------------|
| `zoom_extents` | Zoom to show all entities |
| `zoom_window` | Zoom to a specified window |
| `get_screenshot` | Capture current AutoCAD view as PNG |
Screenshots use `PrintWindow` (Win32) for the File IPC backend — works even when AutoCAD is minimized or in the background. The ezdxf backend renders via matplotlib.
### `system` — Server management
`status`, `health`, `get_backend`, `runtime`, `init`, `execute_lisp`
> `execute_lisp` runs arbitrary AutoLISP code (File IPC only). Pass `data: {code: "(+ 1 2)"}`. This turns the server into an extensible automation platform — any valid AutoLISP expression can be executed.
## Architecture
```
MCP Client (Claude)
│ stdio (JSON-RPC)
▼
Python MCP Server (autocad_mcp)
│
├── File IPC Backend ──► C:/temp/*.json ──► mcp_dispatch.lsp (AutoCAD LT)
│ PostMessageW(WM_CHAR) to MDIClient — no focus steal
│
└── ezdxf Backend ──► in-memory DXF (headless, no AutoCAD needed)
```
The File IPC backend sends keystrokes to AutoCAD's MDIClient window via `PostMessageW(WM_CHAR)`, invoking `(mcp-dispatch-v2 "<request-id>")` for one specific request. The target is rediscovered and validated on each dispatch, and Windows delivery errors are reported. This approach does **not** steal window focus — you can continue working in other applications while automation runs.
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `AUTOCAD_MCP_BACKEND` | `auto` | Backend selection: `auto`, `file_ipc`, `ezdxf` |
| `AUTOCAD_MCP_IPC_DIR` | `C:/temp` | Directory for IPC command/result JSON files (must match on both Python and LISP sides) |
| `AUTOCAD_MCP_IPC_TIMEOUT` | `30.0` | IPC command timeout in seconds (1-300) |
| `AUTOCAD_MCP_IPC_LONG_TIMEOUT` | `120.0` | Timeout for `execute_lisp` and plotting (up to 600) |
| `AUTOCAD_MCP_AUTOLOAD` | `1` | Load `mcp_dispatch.lsp` in the active document before its first v2 request (`0` requires manual preload) |
| `AUTOCAD_MCP_ONLY_TEXT` | `false` | Disable screenshot capture (text feedback only) |
> **Note:** If you change `AUTOCAD_MCP_IPC_DIR`, you must also update the `*mcp-ipc-dir*` variable in `mcp_dispatch.lsp` to match.
## Development
```powershell
uv sync
uv run pytest tests/ -v
```
## AutoCAD LT AutoLISP Compatibility
AutoLISP was added to AutoCAD LT in the **2024 release (Windows only)**. AutoCAD LT for Mac does not support AutoLISP.
| Supported (LT 2024+ Windows) | Not Supported |
|-------------------------------|---------------|
| `.lsp` / `.fas` / `.vlx` / `.dcl` | VLIDE (Visual LISP IDE) |
| Supported `vl-*` and selected `vla-*`/`vlax-*` functions | Full ActiveX/COM API parity |
| File I/O (`open`, `read-line`, etc.) | Express Tools |
| Entity access (`entget`, `entmod`, etc.) | 3D operations |
| Selection sets | AutoLISP on Mac |
The revision helper was exercised in Windows AutoCAD LT 2027. It uses selected
`vla-*`/`vlax-*` functions available inside that runtime; this does not imply support
for the complete ActiveX API or external COM automation. Qualify required operations
on a disposable drawing for other releases.
After a document switch, a stale cached command window can prevent command pickup.
Inspect the desktop and pending receipts first. If the command was never picked up
and no mutation occurred, `system(operation="init")` refreshes the connection; verify
the active drawing again before resuming. Do not use reinitialization to bypass an
uncertain completion hold.
## What's New in v3.1
- **`execute_lisp`** — Run arbitrary AutoLISP code via temp file pattern. Turns the server from a fixed command set into an extensible automation platform.
- **Undo / Redo** — Single-step undo and redo via `drawing` tool.
- **Drawing open** — Open existing `.dwg` files programmatically (FILEDIA suppressed).
- **Drawing create** — Now resets current drawing (erase all + purge) instead of `_.NEW`, preserving the LISP dispatcher namespace.
- **Drawing save with path** — `save` with a `path` parameter uses SAVEAS; without path uses QSAVE.
- **`get_variables` fix** — Respects the `names` parameter; returns requested variables with proper type handling.
- **Polyline/leader fix** — Point arrays properly encoded via semicolon-delimited format.
- **ESC prefix** — Sends 2x ESC before each dispatch to cancel stale pending commands from prior timeouts.
- **UTF-8/cp1252 fallback** — Handles non-ASCII characters in LISP result files (AutoCAD writes Windows-1252).
- **Configurable IPC timeout** — `AUTOCAD_MCP_IPC_TIMEOUT` env var (1–300 seconds, default 30); `execute_lisp` and plotting use `AUTOCAD_MCP_IPC_LONG_TIMEOUT` (default 120).
- **Dispatcher autoload** — `mcp_dispatch.lsp` is loaded per drawing. The v2 trigger loads it before dispatch in a document that lacks protocol 2. There is no automatic second trigger or command replay. Disable with `AUTOCAD_MCP_AUTOLOAD=0`.
- **Thread-safe backend init** — `asyncio.Lock` prevents parallel initialization races.
### File IPC v2 recovery
Deploy `src/autocad_mcp` and `lisp-code/mcp_dispatch.lsp` together and restart the
Python MCP process. V2 uses `pcad-v2-<id>.ready.json`, `.claimed.json`,
`.cancelled.json` and `.result.json`; legacy wildcard dispatchers cannot consume
these files. AutoLISP claims by same-directory rename **before reading**. Python
can instead rename ready to cancelled. Only the winning rename authorizes execution.
A delayed trigger names its old ID and cannot run a newer request.
`pcad-pending.json` fences subsequent clients until completion or reconciliation.
On `IPC_NOT_PICKED_UP_CANCELLED`, stop edits and inspect `system.desktop` and its
screenshot. `cancelled_before_claim: true` is verifiable non-execution evidence;
`system.acknowledge` with the exact ID can preserve it and release the fence.
It does not automatically resend a request or clear partially typed input. If the
claim exists, reconcile native handles and the matching late result before
acknowledgement. Missing files alone are never evidence of non-execution.
Legacy pending markers still need explicit recovery; their old read/delete protocol
cannot supply a v2 cancellation proof. Retain them with the recovery record.
Windows process launch failures from WSL (`UtilAcceptVsock ... accept4 failed 110`)
are a different transport layer. Preserve the pending receipt and check interop and
kernel logs; do not use AutoCAD retries to diagnose WSL. See `docs/ipc-v2.md` for
protocol invariants, deployment/rollback and qualification status.
## Reliable execution
Bounded edit/readback/screenshot batches and automatic recovery saves are execution
checks, not review gates.
Keep one Windows MCP process alive for the job. `system.job launch/attach/close`
runs on Windows without additional WSL process launches. `close` saves first and
requires a stopped worker and DBMOD=0. It never discards unsaved changes or kills an
unrelated AutoCAD process. `system.worker renew` renews the same document at a safe
boundary. Request uncertainty stops mutations; no timeout is automatically replayed.
The [queue workflow](docs/queue-workflow.md) documents qualification and operational
limits. Earlier keyboard-trigger qualification in `docs/ipc-v2.md` is historical;
it does not qualify the current worker build.
## License
MIT
TDQS
Scored across 8 tools
Each tool category has a distinct purpose with clear boundaries: annotation for annotations, block for blocks, drawing for file management, entity for entity operations, layer for layers, pid for P&ID, system for server management, and view for viewport control. Within categories, operations are well-differentiated by specific actions and target entities, with no significant overlap that would cause confusion.
Tool names are highly consistent within categories, using clear verb_noun patterns (e.g., create_text, list_layers, zoom_extents). There are minor deviations, such as 'get_screenshot' (verb_noun) vs. 'zoom_extents' (verb_adjective), and some operations like 'undo' or 'redo' are single verbs, but overall the naming is predictable and readable across the set.
With 8 tools, the server is well-scoped for AutoCAD LT AutoLISP functionality, covering essential domains like drawing management, entity creation, annotation, and specialized P&ID tasks. Each tool category serves a distinct purpose, and the total count is manageable without being overwhelming or too sparse for the domain.
The tool set provides comprehensive coverage for AutoCAD LT operations, including full CRUD/lifecycle for entities, layers, and blocks, along with drawing file management, annotation, P&ID-specific functions, system controls, and viewport manipulation. There are no obvious gaps; agents can perform complete workflows from creation to modification and export.