AutoCAD-MCP

Reliable AutoCAD automation for AI agents, with checked geometry, native 3D, and delivery evidence.

English | 简体中文

AutoCAD-MCP connects Codex, Claude Code, Claude Desktop, Cursor, and any standard MCP client to full AutoCAD, AutoCAD LT, or a headless DXF backend. It is built for agents that must prove what they drew, not merely report that a script ran.

Why AutoCAD-MCP

• Checked writes: strict inputs, handle readback, requested/actual diffs, and document revisions. Native-worker transactions are atomic; compatibility COM/LISP paths report compensation limits instead of promising rollback they cannot prove.
• Useful CAD coverage: structured 2D drawing, layers, dimensions, topology DRC, native AutoCAD solids and booleans, bounded product features, motion screening, and fixed-camera review views.
• Delivery evidence: DWG/DXF/PDF/PNG outputs, exported-DXF re-audit, paper and scale verification, geometry digests, manifests, and SHA-256 hashes.
• Desktop friendly: AutoCAD stays taskbar-visible but minimized by default, drawing does not steal focus, and preview/PDF viewers are not launched.
• Client neutral: one stdio server for MCP clients; no Codex-only or Claude-only protocol.
• Honest limits: unsupported edge selection, shelling, exact continuous motion, and material rendering are reported explicitly instead of being simulated.

Try It Without AutoCAD

The headless demo creates a mechanical DXF, runs semantic DRC, renders a deterministic PNG, and prints the evidence:

git clone https://github.com/beiming183-cloud/AutoCAD-MCP.git
cd AutoCAD-MCP
uv sync
uv run python examples/headless_demo.py

Expected result: ok: true, six entities, and drc_status: PASS. Outputs are written to demo-output/ unless AUTOCAD_MCP_OUTPUT_ROOT is set.

Native AutoCAD Showcase

With a healthy, manually opened AutoCAD session, reproduce the promotional rotary actuator as editable native solids:

uv run python examples/generate_actuator_promo.py --record --pause 1.0

Recording mode activates AutoCAD once, creates a blank document, frames the planned model before the first write, pauses one second after each completed semantic step, and leaves the final document open. It deliberately skips PNG/PDF rendering and final rotation so no viewer or camera motion interrupts capture.

Choose a Backend

| Backend | Runtime | Requires AutoCAD? | Validation feedback | |---------|---------|-------------------|------------| | Native worker | Windows Python | Full AutoCAD 2025/2026 | Database transactions, revision events, feature IDs, native 2D/3D | | File IPC compatibility | Windows Python | Full AutoCAD or AutoCAD LT 2024+ | COM/LISP coverage, topology audit, PDF and PNG | | ezdxf | Any platform | No (headless) | Structured audit + deterministic PNG |

The server exposes 12 consolidated tools (drawing, entity, solid, product, layer, block, annotation, pid, transaction, view, job, system) over standard MCP stdio.

This edition is based on puran-water/autocad-mcp and retains its MIT license. Version 4.0 adds a native transactional worker, client-independent named-pipe protocol, external desktop supervisor, durable idempotency journal, and database-owned document revisions while retaining COM/LISP compatibility.

For startup failures caused by a damaged Python COM environment, an orphaned acad.exe, or Activity Insights permissions, use the Windows AutoCAD recovery runbook. system(operation="preflight") is read-only and does not start AutoCAD.

Prerequisites (File IPC backend)

• Windows 10/11 (the File IPC backend uses Win32 APIs for focus-free window messaging)
• Full AutoCAD or AutoCAD LT 2024+ on Windows - AutoLISP support was added to LT in 2024; full AutoCAD also uses the native COM path.
• Python 3.10+ (Windows native — not WSL Python)
• uv package manager (install guide)

The ezdxf headless backend works on any platform (Linux, macOS, WSL) for offline DXF generation without AutoCAD installed.

Quick Start

1. Clone and install

git clone https://github.com/beiming183-cloud/AutoCAD-MCP.git
cd AutoCAD-MCP
uv sync

2. Install the signed native worker (full AutoCAD 2025/2026)

The preferred industrial path is the .NET 8 worker under native/. It executes mutations under DocumentLock plus a native database transaction and publishes a current-user named pipe. Build, Authenticode-sign, verify, and install it with:

$env:AUTOCAD_MCP_AUTOCAD_DIR = "D:\cad\AutoCAD 2025"
.\native\scripts\build-plugin.ps1 `
  -AutoCADDir $env:AUTOCAD_MCP_AUTOCAD_DIR `
  -DotNet "D:\Codex\Tools\dotnet-sdk\dotnet.exe" `
  -CertificateThumbprint "YOUR_CODE_SIGNING_CERT_THUMBPRINT" `
  -Install

Installation refuses an unsigned DLL. Keep AutoCAD SECURELOAD enabled. The bundle loads at AutoCAD startup and writes its worker descriptor to %LOCALAPPDATA%\AutoCAD-MCP\workers.

For a stable desktop session, start the user-owned supervisor from an ordinary PowerShell window, not from an MCP client's sandbox:

$env:AUTOCAD_MCP_OUTPUT_ROOT = "D:\Codex\AutoCAD-MCP"
autocad-mcp-supervisor run `
  --acad-exe "D:\cad\AutoCAD 2025\acad.exe" `
  --window-mode quiet_minimized `
  --output-root "D:\Codex\AutoCAD-MCP"

The supervisor leaves AutoCAD visible in the taskbar but minimized, never opens PDF/PNG viewers, and leaves AutoCAD running when supervision stops. Use autocad-mcp-supervisor status from another terminal to inspect PID, HWND, heartbeat, fatal-window state, and native-worker discovery.

3. Load the LISP dispatcher for LT or compatibility fallback

Open AutoCAD or AutoCAD LT and load mcp_dispatch.lsp using APPLOAD:

1. Type APPLOAD in the AutoCAD command line
2. Browse to <repo>/lisp-code/mcp_dispatch.lsp
3. Click Load
4. You should see: === MCP Dispatch v4.0.0 loaded === and Ready for commands via (c:mcp-dispatch)

Tip: Add the file to your AutoCAD Startup Suite (in the APPLOAD dialog) so it loads automatically with every drawing.

4. Configure your MCP client

Add to your MCP client configuration (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "autocad-mcp": {
      "command": "C:\\path\\to\\autocad-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "autocad_mcp"],
      "env": {
        "AUTOCAD_MCP_BACKEND": "file_ipc",
        "AUTOCAD_MCP_LISP_PATH": "C:\\path\\to\\autocad-mcp\\lisp-code\\mcp_dispatch.lsp"
      }
    }
  }
}

The same server command can be used in Claude Code project-level .mcp.json:

{
  "mcpServers": {
    "autocad": {
      "type": "stdio",
      "command": "C:\\path\\to\\autocad-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "autocad_mcp"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\autocad-mcp\\src",
        "AUTOCAD_MCP_BACKEND": "file_ipc",
        "AUTOCAD_MCP_NATIVE_PLUGIN": "auto",
        "AUTOCAD_MCP_AUTOSTART": "false",
        "AUTOCAD_MCP_VISIBLE": "true",
         "AUTOCAD_MCP_WINDOW_MODE": "preserve",
        "AUTOCAD_MCP_ACTIVATE_ON_DRAW": "false",
        "AUTOCAD_MCP_OUTPUT_ROOT": "D:/Codex/AutoCAD-MCP",
        "AUTOCAD_MCP_ACTIVITY_INSIGHTS_PATH": "D:/Codex/AutoCAD-MCP/activity-insights"
      }
    }
  }
}

Key points:

• The command must point to the Windows Python inside the project venv (not WSL python).
• AUTOCAD_MCP_BACKEND can be auto (tries File IPC, then falls back to ezdxf), file_ipc (recommended for engineering drawings), or ezdxf (headless only).
• Full AutoCAD prefers the native worker. COM/LISP remains a compatibility path; AutoCAD LT uses LISP/window messaging.
• AUTOCAD_MCP_NATIVE_PLUGIN=required fails closed when the signed native worker is absent; auto falls back to COM/LISP.
• Prefer the desktop supervisor over MCP-owned startup. AUTOCAD_MCP_AUTOSTART=true remains available for compatibility.
• When attaching to a CAD instance opened by a user, startup/profile/window policy is read-only: it does not rewrite Activity Insights variables or change the window unless AUTOCAD_MCP_APPLY_ACTIVITY_POLICY=true or AUTOCAD_MCP_APPLY_WINDOW_POLICY_TO_EXISTING=true is explicitly set.

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:

{
  "mcpServers": {
    "autocad-mcp": {
      "type": "stdio",
      "command": "cmd.exe",
      "args": ["/d", "/s", "/c", "cd /d C:\\path\\to\\autocad-mcp && .venv\\Scripts\\python.exe -m autocad_mcp"],
      "env": { "AUTOCAD_MCP_BACKEND": "auto" }
    }
  }
}

5. 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.

Optional industrial design Skill

skills/industrial-product-design is a client-neutral upstream workflow for briefs, concept gates, product architecture, configurations, motion, camera/render evidence, and honest CAD capability checks. Install or reference that folder in any SKILL.md-compatible client, then use mechanical-drafting-gbt downstream for GB/T manufacturing definition and release.

skills/industrial-product-design-gbt is the comprehensive variant. It adds research-source authority, human-factors evidence, form and surface review, backend routing, local reference-library indexing, and deterministic checks for document identity, 2D/3D interfaces, motion states, render viewsets, and revision-bound handoff manifests. Its personal library manifest is intentionally ignored; generate one locally from the included portable schema.

Tools

drawing — File/drawing management

| Operation | Description | File IPC | ezdxf | |-----------|-------------|----------|-------| | create | Create and activate a new document, optionally at a managed path | Yes | Yes | | context | Return active document ID, path, and monotonic revision | Yes | Yes | | activate | Activate a doc_id at an exact expected_revision, then verify active-document readback | Yes | Limited | | 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 without switching the active DWG | Yes | Yes | | plot_pdf | Plot to PDF | Yes | No | | render_preview | True PNG with DPI, force-overwrite, dimensions, and SHA-256 | Yes | Yes | | workspace | Create and report the managed output workspace | Yes | Yes | | deliver | Validated DWG/DXF/PDF package with manifest and checksums | Yes | No | | audit | Compact structured entity audit with change tracking | Yes | Yes | | audit_geometry | Geometry/topology DRC including gaps, dangling endpoints, crossings, tangency, equal radii, and projection checks | Yes | Yes | | audit_dxf | Parse an existing DXF into normalized JSON | Yes | Yes | | setup_mechanical | Configure mm units, dimensions, sheet metada