{
"markdown": "# best-cad-mcp\n\n\n\n[](https://pypi.org/project/best-cad-mcp/)\n[](https://pypi.org/project/best-cad-mcp/)\n\n[](https://github.com/LokmenoWer/best-cad-mcp/blob/master/LICENSE)\n\n**A local, handle-first MCP server for agents that work with real AutoCAD drawings.**\n\nInspect a DWG, reason over structured geometry, plan guarded edits, validate the\nresult, and export visual evidence without hiding agent state inside the drawing.\n\n[简体中文](https://github.com/LokmenoWer/best-cad-mcp/blob/master/README.zh-CN.md) · [Live demo](#live-autocad-demo) · [Install](#quick-start) · [Workflow](#the-guarded-workflow) · [Tool profiles](#tool-profiles) · [Safety](#safety-model) · [Limitations](#known-limitations)\n\n\n\n*A real AutoCAD model-space export created by a validated, dry-run CADPlan:\nfront and top projections, a sectioned side view, centerlines, dimensions,\nfeature callouts, hatches, and a title block. Download the\n[source DWG](https://raw.githubusercontent.com/LokmenoWer/best-cad-mcp/master/docs/artifacts/readme-real-cad/bearing-housing-three-view.dwg)\nor inspect the [executed CADPlan](https://github.com/LokmenoWer/best-cad-mcp/blob/master/docs/artifacts/readme-real-cad/cadplan.json).*\n\n> [!IMPORTANT]\n> best-cad-mcp is beta software. It is designed for controlled local workflows\n> where an operator can review plans and evidence, not unattended changes to\n> valuable production drawings.\n\n## Why best-cad-mcp\n\nMost CAD automation stops at drawing primitives. Useful agent workflows also\nneed to know exactly **what** they are changing, **why** a target was selected,\nand **whether** the result is correct.\n\n| Handle-first control | Drawing understanding | Evidence before trust |\n| --- | --- | --- |\n| Scan real AutoCAD handles, query exact entities, and edit those handles instead of guessing from labels or pixels. | Build CAD-IR, semantic objects and graphs, dimension bindings, constraints, and validation reports in a local workspace. | Validate and dry-run CADPlans, execute explicitly, rescan, and compare structured and visual results. |\n\nThe server runs on the same Windows account as AutoCAD and communicates over\nMCP stdio. It runs natively on the official MCP Python SDK 2.x, negotiates the\n2026-07-28 protocol, and retains legacy client negotiation. AutoCAD remains the\nsource of truth; SQLite stores model-private context, scan results, and review\nartifacts alongside the workspace. AutoCAD-facing tool calls are intentionally\nserialized on one event-loop thread to preserve COM apartment safety.\n\n## Live AutoCAD demo\n\n> **Prompt:** Create a production-style A3 landscape bolted flange-coupling\n> assembly drawing at true 1:1 size, with a longitudinal half-section, aligned\n> end view, exploded schematic, true dimensions, differentiated hatching, an\n> eight-item BOM, matching item leaders, technical requirements, and a\n> controlled title block.\n\n\n\nThis is the result of a live AutoCAD session, not a hand-authored SVG. The MCP\nclient loaded the shipped `precise_draw_from_spec` prompt, then ran 18 bounded\ngeneration phases (162 steps). Its autonomous visual-repair loop used two\nlayout-repair plans (4 steps); three separately recorded, operator-authorized\npresentation-only release-QA plans added 10 steps. Every plan was validated and\ndry-run before transactional execution. The final\nrescan indexed 91 entities; structured verification detected 129 semantic\nobjects, processed 7 true dimension annotations, and checked 134 constraints\n(127 satisfied, 7 unknown, and none violated). Post-repair geometry validation reported zero\nissues. The release plot was independently checked as a one-page landscape A3\nPDF.\n\nFor reproducibility, the checked-in MCP client builds the deterministic\nCADPlans used for this recorded run. The demo shows live execution of the\noptimized prompt's guarded workflow, not an unscripted one-shot LLM\ngeneration.\n\n[DXF](examples/live-flange-coupling-demo/flange-coupling-assembly-final.DXF)\n· [A3 PDF](examples/live-flange-coupling-demo/flange-coupling-assembly-readme-demo.pdf)\n· [Exact prompt](examples/live-flange-coupling-demo/prompt.md)\n· [CADPlan bundle](examples/live-flange-coupling-demo/cadplans.json)\n· [Verification report](examples/live-flange-coupling-demo/verification-report.json)\n· [MCP client](examples/live-flange-coupling-demo/generate_demo.py)\n\nThe drawing follows the repository's generic mechanical assembly practice and\nis marked `DEMO - NOT FOR MANUFACTURE`; it does not claim formal ISO, GB, ASME,\nor other standards compliance.\n\n## Quick start\n\n### Requirements\n\n- Windows\n- AutoCAD 2020 or newer recommended, installed and licensed\n- AutoCAD and the MCP client running as the same Windows user\n- Python 3.11 or newer\n- An MCP-compatible local client\n\n### Install the package\n\n```powershell\npython -m pip install --upgrade best-cad-mcp\ncad-mcp-doctor --check-autocad\n```\n\nFor rendered overlays and visual-review helpers:\n\n```powershell\npython -m pip install --upgrade \"best-cad-mcp[visual]\"\ncad-mcp-doctor --check-autocad --require-visual-export\n```\n\nKeep AutoCAD open, then configure your MCP client to launch `cad-mcp`.\n\n### Codex\n\nCodex supports both global `~/.codex/config.toml` and trusted,\nproject-scoped `.codex/config.toml` files. This minimal installed-package\nconfiguration uses the curated `core` tool profile:\n\n```toml\n[mcp_servers.best-cad-mcp]\ncommand = \"cad-mcp\"\ncwd = 'C:\\CAD\\your-project'\nenabled = true\nstartup_timeout_sec = 30\ntool_timeout_sec = 120\ndefault_tools_approval_mode = \"writes\"\n\n[mcp_servers.best-cad-mcp.env]\nCAD_MCP_TOOL_PROFILE = \"core\"\nCAD_MCP_WORKSPACE_ROOT = 'C:\\CAD\\your-project'\n```\n\nRestart Codex after editing the file, then inspect the connected server with\n`/mcp`. See the\n[official Codex MCP configuration guide](https://developers.openai.com/codex/mcp)\nfor configuration scopes and current options.\n\n### Claude Code and other JSON-configured clients\n\n```json\n{\n \"mcpServers\": {\n \"best-cad-mcp\": {\n \"command\": \"cad-mcp\",\n \"env\": {\n \"CAD_MCP_TOOL_PROFILE\": \"core\",\n \"CAD_MCP_WORKSPACE_ROOT\": \"C:\\\\CAD\\\\your-project\"\n }\n }\n }\n}\n```\n\nSave this as `.mcp.json` in the CAD project root and start the client from that\nproject. `CAD_MCP_WORKSPACE_ROOT` should point to the CAD project being worked\non, not to this repository. With an installed package, setting both the process\n`cwd` and workspace root to the project keeps runtime files together.\n\n\nInstall from source
\n\n```powershell\ngit clone https://github.com/LokmenoWer/best-cad-mcp.git\ncd best-cad-mcp\npython -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\npython -m pip install --upgrade pip\npython -m pip install -e \".[visual]\"\n.\\.venv\\Scripts\\python.exe -m src.doctor --check-autocad\n```\n\nFor a source checkout, start `python -m src.server` from the repository or\nset the MCP server `cwd` to the repository. Keep\n`CAD_MCP_WORKSPACE_ROOT` pointed at the separate CAD project you want to\nindex.\n\n \n\n## The guarded workflow\n\n\n\n1. **Preflight** — run `check_runtime_environment(check_autocad=true)` or\n `cad-mcp-doctor --check-autocad`; stop when the result reports `ok=false`.\n2. **Scan** — run `scan_all_entities` before reasoning about an existing DWG.\n Use `topology_detail=\"full\"` for primitive grounding or cross-entity profiles.\n3. **Understand** — build CAD-IR, summarize the drawing, query semantics, and\n confirm important targets with `explain_entity`.\n4. **Plan** — express multi-step changes as a CADPlan, then call\n `validate_cad_plan` and `dry_run_cad_plan`.\n5. **Execute explicitly** — only after authorization and an acceptable dry-run,\n call `execute_cad_plan(..., allow_modify=true, transactional=true)`.\n6. **Verify** — rescan, run geometric validation, export a clean view and\n overlay, and save only when the operator intends to persist the DWG.\n\nFor precise edits, prefer handles returned by AutoCAD over names inferred from\nscreenshots. For visual findings, treat grounding as evidence: confirm the\ncandidate entity and its geometry before changing it.\n\n## What it can do\n\n| Area | Representative capabilities |\n| --- | --- |\n| 2D drafting | Lines, polylines, curves, circles, regions, hatches, text, dimensions, leaders, tables, layers, blocks, and attributes |\n| Editing | Move, copy, rotate, scale, mirror, offset, trim, extend, fillet, chamfer, arrays, properties, selections, and handle-targeted changes |\n| Drawing understanding | SQLite scan, CAD-IR v2, summaries, semantic objects/graphs, constraints, dimension binding, validation, and repair proposals |\n| Guarded automation | CADPlan variables, dependencies, captured handles, preconditions, postconditions, dry-runs, transactional execution, undo, and rollback attempts |\n| Visual grounding | Clean exports, adaptive numeric overlays, pixel/world mapping, path and polygon grounding, tile crops, and VLM finding reconciliation |\n| Image-to-CAD | ImageDrawingSpec tracing, calibration, fidelity checks, staged execution, and visual comparison against the source image |\n| Mechanical drawings | Orthographic views, sections, hatches, centerlines, dimensions, BOMs, balloons, layouts, and assembly-oriented prompt/skill assets |\n| 3D and output | 3D solids and operations, layouts, plotting, PDF/DXF/DWF/image export, and direct in-result image content |\n\n### Tool profiles\n\nThe shipped client configs and examples recommend `core` because it keeps tool\nselection reliable while covering normal guarded workflows. When the profile\nenvironment variable is omitted, the Python server falls back to `full` for\nbackward compatibility.\n\n| Profile | Tools | Intended use |\n| --- | ---: | --- |\n| `lean` | 114 | Smallest dependable surface for common drawing and inspection tasks |\n| `core` | 215 | Recommended default for full guarded CAD workflows |\n| `full` | 322 | Every registered tool, including specialized and legacy operations |\n\nSelect a profile with `CAD_MCP_TOOL_PROFILE=lean|core|full`. Fine-grained\nallow/deny controls are also available through\n`CAD_MCP_TOOLS_INCLUDE` and `CAD_MCP_TOOLS_EXCLUDE`.\n\n## From visual understanding to grounded CAD evidence\n\nThe hero is not an explanatory mockup. It was drawn in a new AutoCAD document\nthrough a 90-step CADPlan, scanned as 81 real entities, validated with zero\ngeometry issues, exported as WMF, and rasterized to the PNG shown above. The\nsource DWG, plan, dry-run, validation output, pixel/world mapping, and VLM\nreview are retained as reviewable artifacts.\n\nA VLM review should return more than a caption. Below are real artifacts from\nthe same snapshot: the clean AutoCAD tile inspected by the model and its actual\nhandle overlay. They are raster crops produced by the mapping tool, not redrawn\ndocumentation graphics.\n\n| Clean AutoCAD raster tile | Handle overlay from the same snapshot |\n| --- | --- |\n|  |  |\n\nThe overlay is registered to the WMF selection-export frame, not to the active\nviewport. AutoCAD's measured proportional frame margin is preserved while the\nold generic viewport padding is excluded. In this capture the mapped front-view\norigin is `(734.870, 331.032)` px and the cyan centerline intersection observed\nin the real raster is `(735, 331)` px: a maximum error of `0.13 px`.\n\nThe real `vlm_review_drawing/v3` result was schema-validated and submitted\nwithout pre-claiming handles. Its four regions are authored from the raster and\nlocked to that raster's dimensions and SHA-256; the capture script rejects them\nif AutoCAD produces a different image. Grounding resolved the central bore to handle\n`8A`, the rounded mounting-slot profile to `115`, and the title-block semantic\ngroup to `236`. The section hatch correctly remained ambiguous because two\nreal hatch candidates had a narrow score margin.\n\n```json\n{\n \"central_bore\": {\"status\": \"grounded\", \"handles\": [\"8A\"]},\n \"mounting_slot\": {\"status\": \"grounded\", \"handles\": [\"115\"]},\n \"section_hatch\": {\"status\": \"ambiguous\", \"handles\": []},\n \"title_block\": {\"status\": \"grounded\", \"handles\": [\"236\"]}\n}\n```\n\nInspect the [hash-locked visual observation](https://github.com/LokmenoWer/best-cad-mcp/blob/master/docs/artifacts/readme-real-cad/vlm-review-observed.json),\n[submitted VLM return](https://github.com/LokmenoWer/best-cad-mcp/blob/master/docs/artifacts/readme-real-cad/vlm-review-raw.json),\n[grounded result](https://github.com/LokmenoWer/best-cad-mcp/blob/master/docs/artifacts/readme-real-cad/vlm-review-grounded.json),\n[pixel/world alignment check](https://github.com/LokmenoWer/best-cad-mcp/blob/master/docs/artifacts/readme-real-cad/view-alignment-check.json),\n[CADPlan dry-run](https://github.com/LokmenoWer/best-cad-mcp/blob/master/docs/artifacts/readme-real-cad/cadplan-dry-run.json),\nand [zero-issue geometry validation](https://github.com/LokmenoWer/best-cad-mcp/blob/master/docs/artifacts/readme-real-cad/geometry-validation.json).\n\n### Copy a mechanical drawing from one image\n\nThe full path separates non-mutating understanding from the one explicitly\nauthorized DWG modification stage, then closes with a rescan and visual diff.\nThis README does not present a generated flow illustration as trace evidence;\na real run should retain the source raster, `ImageDrawingSpec`, validated and\ndry-run CADPlan, resulting DWG, and final AutoCAD export.\n\nA typical tracing loop is:\n\n1. call `prepare_image_trace(image_path, domain=\"mechanical\")`;\n2. use `prepare_visual_semantic_context` and `get_trace_source_image` to inspect\n global and tiled source images;\n3. produce `ImageDrawingSpec/v1`, echoing each observed image's\n `source_ref_template` for measured coordinates;\n4. call `validate_image_drawing_spec`, then `submit_image_drawing_spec`;\n5. call `compile_image_spec_to_cad_plan`;\n6. call `validate_image_fidelity_contract(spec, cad_plan)`;\n7. call `validate_cad_plan`, then `dry_run_cad_plan`;\n8. only after authorization, call\n `execute_cad_plan(..., allow_modify=true, transactional=true)`;\n9. rescan, validate, and compare the final AutoCAD export with the source.\n\nDo not execute a trace just because its JSON is valid. Check view count,\nsymmetry, dimensions, centerlines, hole placement, and source/render fidelity\nfirst.\n\n## Visual grounding in v1.6\n\nVersion 1.6 adds drawing-level topology for boundaries assembled across\nmultiple entities, including line-line and supported line-curve intersections\nplus closed-loop profiles. Use `scan_all_entities(topology_detail=\"full\")` when\nprimitive relations are required. Grounding now carries real path/polygon\ngeometry, multiple-handle candidates, adaptive overlays, and tile-aware\npixel/world contracts.\n\nThis improves selection quality on mechanical profiles, but it does not make\nvision infallible. Important edits should still follow:\n\n```text\nvisual finding -> grounding candidates -> explain_entity -> handle-targeted edit\n```\n\nThe default VLM review prompt is `vlm_review_drawing/v3`. Snapshot schema\nversions are returned in tool results; overlay schema versions are stored in\nthe referenced sidecars so strict consumers can detect contract changes.\n\n## Safety model\n\n- Read and scan before editing an existing drawing.\n- Keep raw command execution, deletion, purge, audit, save, close, and\n `execute_cad_plan` behind explicit client approval.\n- Validate and dry-run plans before modification.\n- Use returned handles and structured geometry for exact targets.\n- Rescan after modifications; do not rely on stale SQLite rows.\n- Keep model-private notes and spatial annotations in `.cad_mcp/`, not in\n visible DWG geometry, XData, or hidden layers.\n- Treat saving and closing as separate operator decisions.\n- Treat top/plan model-space views as the strongest grounding case. View twist,\n custom UCS, 3D geometry, and complex layout viewports can reduce confidence.\n\nTransaction and rollback support reduce risk but cannot guarantee recovery from\nevery AutoCAD or COM failure. Work on copies when the drawing is valuable.\n\n## Known limitations\n\n- **View grounding is exact only for plan/top model-space views.** An\n untwisted plan view gives numerically stable world↔pixel mapping. View\n twist is included and flagged; non-plan and 3D views fall back to a 2D\n plan-view approximation with `transform_confidence=low` and explicit\n warnings; paperspace/layout viewport mapping is not fully supported. Carry\n returned `limitations` and confidence forward instead of claiming exact\n grounding in those cases.\n- **Raster overlays need the `[visual]` extra.** Without Pillow/cairosvg the\n overlay degrades to an SVG fallback with a warning; WMF exports rely on the\n native Windows GDI+ conversion path.\n- **Dimension binding is heuristic.** Dimensions are matched to candidate\n geometry with evidence and confidence; ambiguous or unbound dimensions stay\n `unknown` by design and are never reported as falsely satisfied.\n- **Semantic detection is deterministic and rule-based.** Richer objects\n (slots, bolt-circle patterns, walls, doors, wires, title blocks, BOM\n tables) are reported as candidates with confidence, not guaranteed\n classifications, and no external model runs inside the server.\n- **CADPlan executes a fixed operation set.** Advanced 3D solids, boolean\n operations, trim/extend, layout editing, plotting, and save/open are not\n plan operations; use the direct MCP tools for those.\n- **Rollback is best-effort.** Transactional execution uses AutoCAD undo\n marks (`StartUndoMark`/`EndUndoMark` + undo); it cannot guarantee recovery\n from every COM or AutoCAD failure, and a failed plan always reports\n `completed_steps` for inspection.\n- **Scans are bounded.** `scan_all_entities` honors `max_entities` and\n reports `truncated` when the drawing exceeds the cap; `topology_detail=\"full\"`\n is expensive on large drawings, so use summary topology by default.\n- **Image tracing depends on the agent-side VLM and calibration.** The server\n prepares, validates, compiles, and enforces fidelity; it never calls a\n model provider. Without reliable dimension calibration, traced drawings\n carry a scale warning and must not be claimed as true engineering scale.\n- **Windows + AutoCAD COM only.** Tool calls are serialized on one COM\n thread, the server must run on the same Windows account as AutoCAD, and\n hosted CI cannot exercise live COM paths — live smoke benchmarks run\n locally via `scripts/verify_cad_understanding_workflow.py`.\n\n## Workspace and data\n\n`CAD_MCP_WORKSPACE_ROOT` controls\n`/.cad_mcp/workspace.db`. The default log, visual exports, and image\ntrace assets are written relative to the MCP process `cwd` as `cad_mcp.log`,\n`cad_visual_exports/`, and `cad_image_traces/`.\n\nExternal CAD projects are not ignored automatically. Add these entries to the\nproject's `.gitignore` when it is a Git repository:\n\n```gitignore\n.cad_mcp/\ncad_mcp.log\ncad_visual_exports/\ncad_image_traces/\n```\n\nThe database helps connect turns and tools, but AutoCAD remains authoritative.\nIf a drawing changes outside the server, scan it again before using stored\nentities. A warning about a legacy root `autocad_data.db` means an older\ndatabase exists; verify migration, then archive it separately.\n\n## Troubleshooting\n\n| Symptom | Check |\n| --- | --- |\n| Server fails to import after upgrading | Run `cad-mcp-doctor --json` with the same Python environment used by the client. best-cad-mcp 1.7+ requires MCP Python SDK `>=2,<3`; upgrade the package/environment and restart the client if `mcp_sdk_version` is blocked. |\n| AutoCAD is open but unavailable | Run `cad-mcp-doctor --check-autocad`; make sure both processes use the same Windows account and privilege level. |\n| Server starts with too many tools | Set `CAD_MCP_TOOL_PROFILE=core` or `lean`, then restart the client. |\n| Visual export is unavailable | The `[visual]` extra provides Pillow for raster overlays. On Windows, AutoCAD WMF uses the native GDI+ fallback; ImageMagick/Wand, Inkscape, or LibreOffice provide alternate paths. Check `get_vision_capabilities()` and `wmf_to_png_available`; PDF can also be rasterized externally. |\n| Queries return stale entities | Activate the intended drawing and rerun `scan_all_entities`. |\n| MCP server starts in the wrong folder | Set server `cwd` to the source checkout only when developing; set `CAD_MCP_WORKSPACE_ROOT` to the CAD project. |\n| A plan is rejected | Run `validate_cad_plan`, inspect the exact failing step, and dry-run again after correcting it. |\n\nFor machine-readable diagnostics:\n\n```powershell\ncad-mcp-doctor --json\n```\n\n## Development\n\n```powershell\ngit clone https://github.com/LokmenoWer/best-cad-mcp.git\ncd best-cad-mcp\npython -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\npython -m pip install -e \".[dev,visual]\"\npython -m pytest -q -m \"not autocad_com\"\n```\n\nRelease publication validates the version, runs the non-COM suite (reserving\nthe `autocad_com` marker for local live-CAD checks), verifies native modern and\nlegacy MCP stdio, builds and clean-installs the wheel, checks it with Twine,\npublishes to PyPI, and then publishes the MCP server metadata. Live AutoCAD\npreflight and CADPlan checks must be run locally because hosted runners do not\nhave AutoCAD.\n\nContributions are welcome. Please keep changes scoped, add regression tests for\nbehavior changes, and preserve the scan → plan → validate → verify safety model.\n\n## Acknowledgements\n\nThe model-private annotation and pointer-style CAD context design was informed\nby the public [Pointer-CAD](https://github.com/Snitro/Pointer-CAD) project and\npaper. No Pointer-CAD source code is copied into this repository.\n\n## License\n\nMIT. See [LICENSE](https://github.com/LokmenoWer/best-cad-mcp/blob/master/LICENSE).\n",
"bytes": 22666,
"sha": "3648ab12c02fb1243ead80aeff75d12f5a686c6acaeba3216e3762ac0adaac94",
"repo_slug": "lokmenower/best-cad-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_lokmenower_best_cad_mcp_f52b7810/readme"
}