best-cad-mcp

# best-cad-mcp

<!-- mcp-name: io.github.LokmenoWer/best-cad-mcp -->

`best-cad-mcp` is a Windows AutoCAD MCP server for agents that need to work with
real DWG projects. It exposes AutoCAD drawing, editing, inspection, metadata,
validation, export, visual grounding, and planning tools through the Model
Context Protocol, with a handle-first workflow designed for safe CAD automation.

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

## What It Does

Most CAD automation examples stop at drawing primitives. `best-cad-mcp` is built
for production-style agent workflows:

- inspect an existing drawing before changing it,
- scan entities, layers, blocks, topology, dimensions, and layouts into a local
  SQLite workspace database,
- explain and edit exact AutoCAD handles,
- build CAD-IR, semantic graphs, constraints, validation reports, and reusable
  resources,
- export clean and annotated views for visual review,
- ground VLM findings from pixels or overlay IDs back to candidate handles, and
- validate, dry-run, and explicitly execute multi-step CADPlans.

The server runs locally, talks to AutoCAD through Windows COM, and stores agent
metadata in the workspace instead of writing hidden helper geometry into the
DWG.

## Highlights

- **290+ MCP tools** for drawing, editing, layers, blocks, attributes, hatches,
  dimensions, tables, layouts, plotting, 3D solids, queries, metadata, and
  workflow guidance.
- **Handle-first editing**: scan first, query structured metadata, then edit the
  precise handles returned by AutoCAD.
- **CAD Understanding Layer** with CAD-IR, drawing summaries, semantic objects,
  semantic graphs, dimension binding, constraints, validation reports, and MCP
  resources.
- **Visual grounding** from exported view pixels, world coordinates, or overlay
  IDs back to likely AutoCAD handles.
- **Guarded CADPlan workflow** with validation, static dry-run, variables,
  `save_as` handle capture, dependencies, postconditions, transactional
  execution, and rollback attempts.
- **Workspace-scoped SQLite memory** for multi-drawing, multi-turn, and
  multi-thread sessions.
- **Model-private annotations** stored in SQLite, not in hidden DWG layers,
  XData, blocks, labels, or marks.
- **Prompt and skill assets** for repeatable drawing understanding, precise
  generation, visual review, repair, and modular assembly drawing standards.

## 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

AutoCAD must be installed, licensed, and able to start on the same Windows
machine where the MCP server runs.

## Installation

Clone the repository and install dependencies:

```powershell
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 -r requirements.txt
python -m pip install -e .
```

Run the server from source:

```powershell
python -m src.server
```

Or run the installed console command:

```powershell
cad-mcp
```

The server is an MCP stdio process. In normal use, your MCP client starts it
automatically from its configuration.

## MCP Client Configuration

Start the MCP client from the workspace whose 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 server from the checkout.

For a user-level Codex configuration after `pip install -e .`, add:

```toml
[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"
```

From a virtual environment checkout:

```toml
[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 on manual approval:

```toml
[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`:

```json
{
  "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 are installed only in the project virtual environment, change
`command` to:

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

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

## First Workflows

### Inspect And Repair An Existing DWG

1. `open_drawing` when the user supplies a DWG path.
2. `scan_all_entities(clear_db=True, detail_level="minimal", topology_detail="summary")`.
3. `build_drawing_ir`.
4. `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. `create_new_drawing`.
2. Set layers, text styles, dimension styles, layout, and units.
3. Build a CADPlan with high-level operations, dependencies, `save_as`
   variables, and postconditions.
4. `validate_cad_plan`, then `dry_run_cad_plan`.
5. `execute_cad_plan(..., allow_modify=True)` only after modification is
   authorized.
6. `scan_all_entities`, `build_drawing_ir`, `validate_geometry`, and export a
   review image.
7. Save or export the final DWG/PDF/DXF/DWF deliverable.

## Core Concepts

### Workspace Database

Runtime metadata is stored by default at:

```text
<workspace>/.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.

Useful workspace tools:

- `get_workspace_context`
- `set_workspace_context`
- `activate_workspace_drawing`
- `list_workspace_drawings`

### CAD Understanding Layer

Understanding tools return structured `ToolResult` dictionaries:

```json
{
  "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.

Key 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`

### CADPlan

CADPlan is the guarded path for multi-step drawing or repair. It is best for
changes that touch multiple entities, need reviewable intent, or should be
dry-run before execution.

```json
{
  "plan_id": "mounting-plate",
  "description": "Draw a plate with four mounting holes",
  "units": "mm",
  "risk_level": "low",
  "requires_confirmation": true,
  "variables": {"origin": [0, 0, 0]},
  "steps": [
    {
      "step_id": "plate",
      "op": "draw_rectangle",
      "args": {"corner1": "$origin", "corner2": [120, 80, 0], "layer": "M-PART"},
      "writes": true,
      "save_as": "$plate",
      "postconditions": [{"type": "exists", "target": "$plate"}]
    }
  ],
  "constraints": [
    {"type": "distance", "expected": 120.0}
  ]
}
```

Executable CADPlan operations include common drawing, editing, layer,
dimension, hatch, and block operations. Valid CAD actions that are not yet bound
inside CADPlan can still be called through their direct MCP tools.

`send_command`, SQL mutation, purge, and audit are disallowed by default in
CADPlan validation.

### Visual Grounding

`export_view_image_with_mapping(include_overlay=True)` creates:

- a clean view export,
- an optional overlay image with numeric IDs,
- a sidecar JSON file with view parameters, visible handles, pixel boxes, and
  mapping data.

Use `ground_vlm_region(snapshot_id, bbox)` for VLM pixel boxes and
`ground_vlm_overlay_id(snapshot_id, overlay_id)` for overlay IDs. Call
`explain_entity` on top candidates before editing.

Top/plan modelspace views are the most reliable. Twisted,