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.

简体中文 · Install · Workflow · Tool profiles · Safety

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.

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

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.

Clean AutoCAD raster tile	Handle overlay from the same snapshot

The real vlm_review_drawing/v3 result was schema-validated and submitted without pre-claiming handles. Grounding resolved the central bore to handle 8A, the rounded mounting-slot profile to 115, and the title-block semantic group to 236. The section hatch correctly remained ambiguous because two real hatch candidates had a narrow score margin.

{
  "central_bore":  {"status": "grounded",  "handles": ["8A"]},
  "mounting_slot": {"status": "grounded",  "handles": ["115"]},
  "section_hatch": {"status": "ambiguous", "handles": []},
  "title_block":   {"status": "grounded",  "handles": ["236"]}
}

Inspect the raw VLM return, grounded result, CADPlan dry-run, and zero-issue geometry validation.

Copy a mechanical drawing from one image

The full path separates non-mutating understanding from the one explicitly authorized DWG modification stage, then closes with a rescan and visual diff. This README does not present a generated flow illustration as trace evidence; a real run should retain the source raster, ImageDrawingSpec, validated and dry-run CADPlan, resulting DWG, and final AutoCAD export.

A typical tracing loop is:

1. call prepare_image_trace(image_path, domain="mechanical");
2. use prepare_visual_semantic_context and get_trace_source_image to inspect global and tiled source images;
3. produce ImageDrawingSpec/v1, echoing each observed image's source_ref_template for measured coordinates;
4. call validate_image_drawing_spec, then submit_image_drawing_spec;
5. call compile_image_spec_to_cad_plan;
6. call validate_image_fidelity_contract(spec, cad_plan);
7. call validate_cad_plan, then dry_run_cad_plan;
8. only after authorization, call execute_cad_plan(..., allow_modify=true, transactional=true);
9. rescan, validate, and compare the final AutoCAD export with the source.

Do not execute a trace just because its JSON is valid. Check view count, symmetry, dimensions, centerlines, hole placement, and source/render fidelity first.

Visual grounding in v1.6

Version 1.6 adds drawing-level topology for boundaries assembled across multiple entities, including line-line and supported line-curve intersections plus closed-loop profiles. Use scan_all_entities(topology_detail="full") when primitive relations are required. Grounding now carries real path/polygon geometry, multiple-handle candidates, adaptive overlays, and tile-aware pixel/world contracts.

This improves selection quality on mechanical profiles, but it does not make vision infallible. Important edits should still follow:

visual finding -> grounding candidates -> explain_entity -> handle-targeted edit

The default VLM review prompt is vlm_review_drawing/v3. Snapshot schema versions are returned in tool results; overlay schema versions are stored in the referenced sidecars so strict consumers can detect contract changes.

Safety model

• Read and scan before editing an existing drawing.
• Keep raw command execution, deletion, purge, audit, save, close, and execute_cad_plan behind explicit client approval.
• Validate and dry-run plans before modification.
• Use returned handles and structured geometry for exact targets.
• Rescan after modifications; do not rely on stale SQLite rows.
• Keep model-private notes and spatial annotations in .cad_mcp/, not in visible DWG geometry, XData, or hidden layers.
• Treat saving and closing as separate operator decisions.
• Treat top/plan model-space views as the strongest grounding case. View twist, custom UCS, 3D geometry, and complex layout viewports can reduce confidence.

Transaction and rollback support reduce risk but cannot guarantee recovery from every AutoCAD or COM failure. Work on copies when the drawing is valuable.

Workspace and data

CAD_MCP_WORKSPACE_ROOT controls <workspace>/.cad_mcp/workspace.db. The default log, visual exports, and image trace assets are written relative to the MCP process cwd as cad_mcp.log, cad_visual_exports/, and cad_image_traces/.

External CAD projects are not ignored automatically. Add these entries to the project's .gitignore when it is a Git repository:

.cad_mcp/
cad_mcp.log
cad_visual_exports/
cad_image_traces/

The database helps connect turns and tools, but AutoCAD remains authoritative. If a drawing changes outside the server, scan it again before using stored entities. A warning about a legacy root autocad_data.db means an older database exists; verify migration, then archive it separately.

Troubleshooting

For machine-readable diagnostics:

cad-mcp-doctor --json

Development

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 -e ".[dev,visual]"
python -m pytest -q -m "not autocad_com"

Release publication validates the version, runs the non-COM suite (reserving the autocad_com marker for local live-CAD checks), verifies native modern and legacy MCP stdio, builds and clean-installs the wheel, checks it with Twine, publishes to PyPI, and then publishes the MCP server metadata. Live AutoCAD preflight and CADPlan checks must be run locally because hosted runners do not have AutoCAD.

Contributions are welcome. Please keep changes scoped, add regression tests for behavior changes, and preserve the scan → plan → validate → verify safety model.

Acknowledgements

The model-private annotation and pointer-style CAD context design was informed by the public Pointer-CAD project and paper. No Pointer-CAD source code is copied into this repository.

License

MIT. See LICENSE.