best-cad-mcp

A local, handle-first MCP server for agents that work with real AutoCAD drawings.

Inspect a DWG, reason over structured geometry, plan guarded edits, validate the result, and export visual evidence without hiding agent state inside the drawing.

简体中文 · Live demo · Install · Workflow · Tool profiles · Safety · Limitations

A real AutoCAD model-space export created by a validated, dry-run CADPlan: front and top projections, a sectioned side view, centerlines, dimensions, feature callouts, hatches, and a title block. Download the source DWG or inspect the executed CADPlan.

[!IMPORTANT] best-cad-mcp is beta software. It is designed for controlled local workflows where an operator can review plans and evidence, not unattended changes to valuable production drawings.

Why best-cad-mcp

Most CAD automation stops at drawing primitives. Useful agent workflows also need to know exactly what they are changing, why a target was selected, and whether the result is correct.

The server runs on the same Windows account as AutoCAD and communicates over MCP stdio. It runs natively on the official MCP Python SDK 2.x, negotiates the 2026-07-28 protocol, and retains legacy client negotiation. AutoCAD remains the source of truth; SQLite stores model-private context, scan results, and review artifacts alongside the workspace. AutoCAD-facing tool calls are intentionally serialized on one event-loop thread to preserve COM apartment safety.

Live AutoCAD demo

Prompt: Create a production-style A3 landscape bolted flange-coupling assembly drawing at true 1:1 size, with a longitudinal half-section, aligned end view, exploded schematic, true dimensions, differentiated hatching, an eight-item BOM, matching item leaders, technical requirements, and a controlled title block.

This is the result of a live AutoCAD session, not a hand-authored SVG. The MCP client loaded the shipped precise_draw_from_spec prompt, then ran 18 bounded generation phases (162 steps). Its autonomous visual-repair loop used two layout-repair plans (4 steps); three separately recorded, operator-authorized presentation-only release-QA plans added 10 steps. Every plan was validated and dry-run before transactional execution. The final rescan indexed 91 entities; structured verification detected 129 semantic objects, processed 7 true dimension annotations, and checked 134 constraints (127 satisfied, 7 unknown, and none violated). Post-repair geometry validation reported zero issues. The release plot was independently checked as a one-page landscape A3 PDF.

For reproducibility, the checked-in MCP client builds the deterministic CADPlans used for this recorded run. The demo shows live execution of the optimized prompt's guarded workflow, not an unscripted one-shot LLM generation.

DXF · A3 PDF · Exact prompt · CADPlan bundle · Verification report · MCP client

The drawing follows the repository's generic mechanical assembly practice and is marked DEMO - NOT FOR MANUFACTURE; it does not claim formal ISO, GB, ASME, or other standards compliance.

Quick start

Requirements

• Windows
• AutoCAD 2020 or newer recommended, installed and licensed
• AutoCAD and the MCP client running as the same Windows user
• Python 3.11 or newer
• An MCP-compatible local client

Install the package

python -m pip install --upgrade best-cad-mcp
cad-mcp-doctor --check-autocad

For rendered overlays and visual-review helpers:

python -m pip install --upgrade "best-cad-mcp[visual]"
cad-mcp-doctor --check-autocad --require-visual-export

Keep AutoCAD open, then configure your MCP client to launch cad-mcp.

Codex

Codex supports both global ~/.codex/config.toml and trusted, project-scoped .codex/config.toml files. This minimal installed-package configuration uses the curated core tool profile:

[mcp_servers.best-cad-mcp]
command = "cad-mcp"
cwd = 'C:\CAD\your-project'
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

[mcp_servers.best-cad-mcp.env]
CAD_MCP_TOOL_PROFILE = "core"
CAD_MCP_WORKSPACE_ROOT = 'C:\CAD\your-project'

Restart Codex after editing the file, then inspect the connected server with /mcp. See the official Codex MCP configuration guide for configuration scopes and current options.

Claude Code and other JSON-configured clients

{
  "mcpServers": {
    "best-cad-mcp": {
      "command": "cad-mcp",
      "env": {
        "CAD_MCP_TOOL_PROFILE": "core",
        "CAD_MCP_WORKSPACE_ROOT": "C:\\CAD\\your-project"
      }
    }
  }
}

Save this as .mcp.json in the CAD project root and start the client from that project. CAD_MCP_WORKSPACE_ROOT should point to the CAD project being worked on, not to this repository. With an installed package, setting both the process cwd and workspace root to the project keeps runtime files together.

git clone https://github.com/LokmenoWer/best-cad-mcp.git
cd best-cad-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[visual]"
.\.venv\Scripts\python.exe -m src.doctor --check-autocad

The guarded workflow

1. Preflight — run check_runtime_environment(check_autocad=true) or cad-mcp-doctor --check-autocad; stop when the result reports ok=false.
2. Scan — run scan_all_entities before reasoning about an existing DWG. Use topology_detail="full" for primitive grounding or cross-entity profiles.
3. Understand — build CAD-IR, summarize the drawing, query semantics, and confirm important targets with explain_entity.
4. Plan — express multi-step changes as a CADPlan, then call validate_cad_plan and dry_run_cad_plan.
5. Execute explicitly — only after authorization and an acceptable dry-run, call execute_cad_plan(..., allow_modify=true, transactional=true).
6. Verify — rescan, run geometric validation, export a clean view and overlay, and save only when the operator intends to persist the DWG.

For precise edits, prefer handles returned by AutoCAD over names inferred from screenshots. For visual findings, treat grounding as evidence: confirm the candidate entity and its geometry before changing it.

What it can do