Best Cad Mcp

best-cad-mcp

best-cad-mcp is a Windows AutoCAD MCP server for agents that need to inspect, reason about, modify, validate, and export real DWG drawings. It runs locally, talks to AutoCAD through Windows COM, and exposes a handle-first CAD automation workflow through the Model Context Protocol.

[Chinese README](README.zh-CN.md)

Project Status

This project is in beta. The main architecture, command-line entry points, workspace database, and core CAD workflows are in place, but the tool surface is still evolving. Treat it as production-oriented infrastructure for controlled local workflows, not as a fire-and-forget CAD robot.

Why This Exists

Most CAD automation demos can draw a line, a circle, or a rectangle. Real agent workflows need more:

• inspect an existing DWG before touching it,
• identify exact AutoCAD handles instead of guessing from labels or screenshots,
• keep drawing understanding, validation reports, and review context across

turns,

• dry-run multi-step edits before they modify the drawing,
• export visual evidence and map VLM findings back to candidate entities, and
• keep private agent annotations out of the DWG itself.

best-cad-mcp is built around those requirements. The server combines broad AutoCAD tool coverage with a local SQLite workspace database, CAD understanding artifacts, visual grounding, prompt assets, and a guarded CADPlan execution path.

What It Provides

| Area | Capabilities | | --- | --- | | AutoCAD operations | Drawing primitives, editing, layers, blocks, attributes, dimensions, tables, hatches, layouts, plotting, view control, 3D solids, file export, queries, selection, and utility tools. | | Handle-first inspection | Scan a drawing into SQLite, query structured metadata, explain entities, and edit by the handles returned by AutoCAD. | | CAD understanding | CAD-IR, drawing summaries, semantic objects, semantic graphs, dimension binding, extracted constraints, validation reports, and MCP resources. | | Visual review | Export clean view images, optional numeric overlays, and sidecar mapping data for pixel/world/entity grounding. | | Direct model vision | Return rendered views, overlays, source images, and trace artifacts as inline MCP image content so a vision-capable model SEES the drawing in the tool result instead of only receiving a file path. | | CADPlan | Validate, dry-run, and explicitly execute multi-step drawing or repair plans with variables, dependencies, captured handles, postconditions, transactional execution, and rollback attempts. | | Agent memory | Store workspace context and model-private spatial annotations in SQLite instead of hiding helper geometry, XData, labels, or marks inside the DWG. | | Prompt and skill assets | Prompt files for understanding, precise drawing, VLM review, and repair; assembly drawing skill references for standards-aware workflows. |

The server currently registers hundreds of MCP tool entry points. The intended workflow is not to call random primitives until a drawing looks right; it is to scan, understand, plan, modify by handle, validate, and visually confirm.

Boundaries

best-cad-mcp does not include AutoCAD, replace an AutoCAD license, or provide a cloud CAD renderer. It assumes AutoCAD is installed and can be automated on the same Windows account that runs the MCP server.

The project also does not promise perfect geometric interpretation from a screenshot. Visual grounding tools return candidates, confidence, and warnings; agents should confirm important targets with explain_entity and structured metadata before editing.

Requirements

• Windows
• AutoCAD 2020 or newer recommended
• Python 3.11 or newer
• An MCP-compatible client such as Codex or Claude Code
• A local AutoCAD installation available through Windows COM automation

Optional visual-review helpers can use system renderers such as ImageMagick, Inkscape, librsvg, Chrome, or Edge, or the Python dependencies installed through the visual extra.

Installation

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 .

Install optional visual-review dependencies:

python -m pip install -e ".[visual]"

Install development dependencies:

python -m pip install -e ".[dev]"

Published Package

For published releases, install the package directly:

python -m pip install best-cad-mcp

The installed console commands are:

cad-mcp
cad-mcp-doctor

The server is an MCP stdio process. In normal use, your MCP client starts it from configuration rather than from an interactive terminal.

Runtime Preflight

Before live CAD work, verify the runtime:

cad-mcp-doctor --check-autocad

The same check is available as an MCP tool:

check_runtime_environment(check_autocad=true, require_visual_export=false)

The preflight reports Windows, Python, package availability, workspace writability, optional visual renderer support, and AutoCAD COM connectivity when check_autocad=true. Treat ok=false as a blocker before drawing or editing.

Strict startup mode is available for deployments that should refuse to start when required checks fail:

$env:CAD_MCP_STRICT_PREFLIGHT = "1"
$env:CAD_MCP_PREFLIGHT_CHECK_AUTOCAD = "1"
$env:CAD_MCP_PREFLIGHT_REQUIRE_VISUAL = "0"
cad-mcp

Set CAD_MCP_PREFLIGHT_REQUIRE_VISUAL=1 when visual export support is a hard runtime requirement.

MCP Client Configuration

Start the MCP client from the workspace whose CAD metadata should be used. Runtime data is stored under that workspace unless CAD_MCP_WORKSPACE_ROOT is set.

Codex

This repository includes .codex/config.toml for project-scoped Codex usage. After trusting the project, Codex can start the local checkout.

User-level configuration after pip install -e . or package installation:

[mcp_servers.best-cad-mcp]
enabled = true
command = "cad-mcp"
cwd = "C:/path/to/best-cad-mcp"
startup_timeout_sec = 30
tool_timeout_sec = 120
default_tools_approval_mode = "approve"

Configuration that runs from a checkout virtual environment:

[mcp_servers.best-cad-mcp]
enabled = true
command = "C:/path/to/best-cad-mcp/.venv/Scripts/python.exe"
args = ["-m", "src.server"]
cwd = "C:/path/to/best-cad-mcp"
startup_timeout_sec = 30
tool_timeout_sec = 120
default_tools_approval_mode = "approve"

Keep raw or destructive tools interactive:

[mcp_servers.best-cad-mcp.tools.send_command]
approval_mode = "prompt"

[mcp_servers.best-cad-mcp.tools.execute_cad_plan]
approval_mode = "prompt"

[mcp_servers.best-cad-mcp.tools.delete_entity]
approval_mode = "prompt"

[mcp_servers.best-cad-mcp.tools.delete_entities]
approval_mode = "prompt"

[mcp_servers.best-cad-mcp.tools.erase_selection_entities]
approval_mode = "prompt"

[mcp_servers.best-cad-mcp.tools.delete_layer]
approval_mode = "prompt"

[mcp_servers.best-cad-mcp.tools.purge_drawing]
approval_mode = "prompt"

[mcp_servers.best-cad-mcp.tools.audit_drawing]
approval_mode = "prompt"

[mcp_servers.best-cad-mcp.tools.save_drawing]
approval_mode = "prompt"

[mcp_servers.best-cad-mcp.tools.close_drawing]
approval_mode = "prompt"

Claude Code

This repository includes:

• .mcp.json, which registers the local stdio server as best-cad-mcp.
• .claude/settings.json, which enables the server and asks before raw or

destructive tools.

The checked-in .mcp.json uses CLAUDE_PROJECT_DIR:

{
  "mcpServers": {
    "best-cad-mcp": {
      "command": "python",
      "args": ["${CLAUDE_PROJECT_DIR:-.}/src/server.py"],
      "env": {
        "CAD_MCP_WORKSPACE_ROOT": "${CLAUDE_PROJECT_DIR:-.}",
        "PYTHONPATH": "${CLAUDE_PROJECT_DIR:-.}"
      }
    }
  }
}

If dependencies live only in the project virtual environment, change command to:

"C:/path/to/best-cad-mcp/.venv/Scripts/python.exe"

Use claude mcp list or /mcp inside Claude Code to confirm that the server is connected.

Tool Profiles

The server registers a very large tool surface. Exposing all of it at once overwhelms model tool selection and some MCP clients cap how many tools they will load, so the most common cause of "I gave the agent lots of tools but they do not work well" is simply too many tools. Pick a profile with the CAD_MCP_TOOL_PROFILE environment variable:

| Profile | Exposed tools | Use when | | --- | --- | --- | | core | curated subset (~210) | Default for the shipped client configs. Covers every documented workflow: scan, understand, draw, edit, dimension, block, hatch, layout, query, CADPlan, visual grounding, direct model vision, and the VLM pipeline. | | lean | essential subset (~113) | You want the smallest reliable surface for inspection and straightforward drawing/editing. | | full | every tool | You explicitly need exotic 3D primitives, preference/plot/material introspection, low-level polyline editing, UCS/viewport/named-view minutiae, and other long-tail tools. |

The shipped .mcp.json and .codex/config.toml set CAD_MCP_TOOL_PROFILE=core. The Python default when the variable is unset is full for backward compatibility. Every profile is a strict superset of the tools referenced by recommend_cad_tools, the workflow playbooks, and tool next_tools hints, so a smaller profile never points the agent at a tool that is not registered.

Fine-tune any profile without editing code:

• CAD_MCP_TOOLS_INCLUDE="draw_torus, get_materials" force-exposes named tools.
• CAD_MCP_TOOLS_EXCLUDE="send_command, purge_drawing" force-hides named tools.

get_tool_help() and cad://tools always reflect the tools that are actually registered under the active profile, and the server logs the active profile and tool count at startup.

Recommended Workflows

Inspect Or Repair An Existing DWG

1. check_runtime_environment(check_autocad=true).
2. open_drawing when the user supplies a DWG path.
3. scan_all_entities(clear_db=true, detail_level="minimal", topology_detail="summary").
4. build_drawing_ir, then summarize_drawing.
5. detect_semantic_objects(domain="mechanical") or another suitable domain.
6. bind_all_dimensions, extract_drawing_constraints, and check_drawing_constraints.
7. validate_geometry.
8. export_view_image_with_mapping(include_overlay=true) when visual evidence matters.
9. ground_vlm_region or ground_vlm_overlay_id for VLM findings.
10. explain_entity(handle) before editing.
11. Edit by handle or through a validated, dry-run CADPlan.
12. Rescan, validate, visually confirm, then save or export.

Create A New Drawing

1. check_runtime_environment(check_autocad=true).
2. create_new_drawing.
3. Set units, layers, text styles, dimension styles, layout, and view state.
4. Build a CADPlan with high-level operations, dependencies, save_as

variables, and postconditions.

1. validate_cad_plan, then dry_run_cad_plan.
2. execute_cad_plan(..., allow_modify=true) only after modification is authorized.
3. scan_all_entities, build_drawing_ir, validate_geometry, and export a review image.
4. Save or export the final DWG, PDF, DXF, or DWF deliverable.

Copy A Mechanical Drawing From One Image

This workflow is for a single external image of a mechanical part or assembly drawing. The VLM call stays on the agent side; MCP validates and compiles the structured result.

1. prepare_image_trace(image_path, domain="mechanical").
2. prepare_visual_semantic_context(image_id) to gather normalized,

high-contrast, and edge-emphasized VLM inputs plus the open-vocabulary component hypothesis contract.

1. Use the copy_drawing_from_image prompt with the normalized image and tile

index, then ask the VLM for ImageDrawingSpec/v1 JSON.

1. validate_image_drawing_spec(spec, image_id).
2. submit_image_drawing_spec(image_id, spec, source_model=...).
3. compile_image_spec_to_cad_plan(image_id).
4. validate_image_fidelity_contract(spec, cad_plan).
5. validate_cad_plan, then dry_run_cad_plan.
6. Execute only when modification is authorized:

execute_cad_plan(..., allow_modify=true, transactional=true).

1. scan_all_entities, build_drawing_ir, validate_geometry, and

export_view_image_with_mapping(include_overlay=true) for visual diff.

Fidelity rules are strict. A chamfered square must not become a square, a filleted rectangle must keep its radii or arc segments, hole patterns must keep their repeated-feature relationship, and dimensions must become real dimension entities rather than text. If the image is unclear, the spec should record an uncertainty instead of silently guessing or simplifying.

Review With Vision

1. export_view_image_with_mapping(include_overlay=true).
2. Review the clean image, overlay image, and sidecar mapping JSON.
3. Use ground_vlm_overlay_id for overlay IDs or ground_vlm_region for pixel boxes.
4. Confirm candidates with explain_entity.
5. Use propose_repair_plan or propose_constraint_repair_plan for selected issues.

Core Concepts

Workspace Database

Runtime metadata is stored by default at:

/.cad_mcp/workspace.db

The database scopes data by workspace, drawing, conversation, and thread. This keeps identical handles in different drawings from colliding and lets parallel agent sessions keep private annotations and query history separate.

execute_query is read-only, scoped, and bounded. Use public table names such as cad_entities; direct main. access is blocked so one workspace cannot bypass scoped views. Result sets default to 1,000 rows, 5 seconds, and about 1 MB of JSON. Tune with tool parameters or:

• CAD_MCP_SQL_MAX_ROWS
• CAD_MCP_SQL_TIMEOUT_MS
• CAD_MCP_SQL_MAX_RESULT_BYTES

Useful workspace tools:

• get_workspace_context
• set_workspace_context
• activate_workspace_drawing
• list_workspace_drawings
• get_database_maintenance_status
• maintain_database
• clear_understanding_cache
• get_legacy_database_status

ToolResult

CAD understanding tools return structured ToolResult dictionaries:

{
  "ok": true,
  "message": "",
  "data": {},
  "handles": [],
  "warnings": [],
  "next_tools": []
}

Read-only understanding tools do not modify the DWG. Semantic objects, constraints, validation reports, view snapshots, and VLM mappings are stored in the workspace database.

scan_all_entities(clear_db=true) clears stale semantic objects, constraints, validation reports, and view snapshots for the active thread by default. Pass clear_understanding=false only when cached understanding artifacts should survive a rescan.

Key understanding tools include:

• build_drawing_ir and export_drawing_ir
• summarize_drawing
• find_entities_by_description
• explain_entity
• detect_semantic_objects, get_semantic_graph, and find_semantic_objects
• bind_dimension_to_geometry and bind_all_dimensions
• extract_drawing_constraints, check_drawing_constraints, and get_drawing_constraints
• validate_geometry and get_validation_report
• propose_repair_plan and propose_constraint_repair_plan
• list_cad_resources and get_cad_resource

build_drawing_ir returns CAD-IR v2 by default. The top-level shape is stable for agents:

{
  "schema_version": "cad-ir/v2",
  "generated_at": "...",
  "manifest": {
    "profile": "agent",
    "sections": ["overview", "entities", "layers"],
    "counts": {},
    "limits": {},
    "warnings": []
  },
  "drawing": {
    "name": "active.dwg",
    "path": "",
    "units": "unknown",
    "extents": {},
    "counts": {}
  },
  "quality": {
    "scan_state": "scanned",
    "coverage": {},
    "issues": [],
    "recommended_next_tools": []
  },
  "sections": {}
}

Use sections to request only the needed payloads: overview, entities, layers, blocks, `topolo

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LokmenoWer
• Source: LokmenoWer/best-cad-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.