best-cad-mcp

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.

Install from source

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

For a source checkout, start python -m src.server from the repository or set the MCP server cwd to the repository. Keep CAD_MCP_WORKSPACE_ROOT pointed at the separate CAD project you want to index.

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

Tool profiles

The shipped client configs and examples recommend core because it keeps tool selection reliable while covering normal guarded workflows. When the profile environment variable is omitted, the Python server falls back to full for backward compatibility.

Select a profile with CAD_MCP_TOOL_PROFILE=lean|core|full. Fine-grained allow/deny controls are also available through CAD_MCP_TOOLS_INCLUDE and CAD_MCP_TOOLS_EXCLUDE.

From visual understanding to grounded CAD evidence

The hero is not an explanatory mockup. It was drawn in a new AutoCAD document through a 90-step CADPlan, scanned as 81 real entities, validated with zero geometry issues, exported as WMF, and rasterized to the PNG shown above. The source DWG, plan, dry-run, validation output, pixel/world mapping, and VLM review are retained as reviewable artifacts.

A VLM review should return more than a caption. Below are real artifacts from the same snapshot: the clean AutoCAD tile inspected by the model and its actual handle overlay. They are raster crops produced by the mapping tool, not redrawn documentation graphics.

The overlay is registered to the WMF selection-export frame, not to the active