autocad-mcp

name	autocad-mcp
description	Read and edit AutoCAD drawings (DWG and DXF), manage XREF attachments and instances, and plot DWG layouts to PDF through the shipped autocad-mcp tool suite. Covers MCP access through autocad-mcp serve and direct CLI access through autocad-mcp call.
when_to_use	Trigger on requests involving .dwg or .dxf drawing operations: title blocks, layers, XREF attachments, XREF instances and dependencies, blocks, text, layouts, or PDF plots. Do not use this skill to write AutoLISP routines or DCL dialogs.

AutoCAD MCP Operations Skill

Use this skill for shipped drawing operations performed by the autocad-mcp tool suite. Use autolisp for AutoLISP authoring.

Do not use this skill to write AutoLISP routines or DCL dialogs. Arbitrary AutoLISP is a contributor/expert technique for designing future operations, not the normal drafter-facing path for supported read, write, or plot workflows.

Invocation Modes

The product has one canonical 51-tool contract through MCP and direct CLI, with an explicit Preview exposure boundary.

• MCP: connect a supported local client to autocad-mcp serve, then call the tools directly.
• CLI: run autocad-mcp call <tool-name> <json-params> for scripting, headless workflows, and repeatable automation.
• Discovery: run autocad-mcp list-tools to print the current tool schemas.

A Release binary is compiled without the preview feature. Its plain serve exposes all 51 certified tools and serve --experimental is an unknown option. A Preview-capable binary exposes exactly the 36 readOnlyHint=true tools through plain serve; serve --experimental explicitly opts into all 51, including the 15 state-changing tools. A visibly marked Preview MCPB supplies that flag in its manifest. Preview plain list-tools and call follow the same 36-tool boundary; use their --experimental option for full-surface discovery or direct dispatch. Release rejects every such experimental option.

The flag changes MCP and direct-CLI tool exposure only. It never bypasses a tool's platform, AutoCAD, ARG/profile, capability, transaction, immutable-source snapshot, race, preservation, verification, or retry checks. Preview has no separate mutation-root restriction: every drawing_path, source path, and output path continues to follow the ordinary per-tool contract below. Preview build, package smoke, and clean-host results are development evidence, not Windows AutoCAD certification or Release evidence.

Every drawing_path is an absolute local path. plot_to_pdf.output is an absolute local PDF path. Every top-level request object is closed: omit inapplicable optional inputs and do not send unknown keys or JSON null values. The properties maps for attachment and instance update are the only open nested objects; their keys are handled by exhaustive runtime property classifiers.

Default Workflow

Read before mutating or plotting.

• Run read_title_blocks before write_title_block.
• Run list_layers before layer mutations.
• Run list_xrefs before targeted attachment operations when identity is unknown, then use the returned attachment handle.
• Run list_xref_instances before targeted instance operations when identity is unknown, then use the returned instance handle.
• Run list_layouts before plot_to_pdf.
• Stop if current drawing state, identity, or destructive scope does not match the requested operation.
• Do not guess title-block profiles, raw tags, layout names, layer identity, attachment identity, instance identity, unit assumptions, or output paths.

Tool Contract

Tool	Required parameters	Optional parameters	Output summary	Platform / notes
list_layers	drawing_path	none	JSON array of expanded LayerRecord objects	DWG and DXF read on all supported hosts
get_layer	drawing_path	handle, name	One expanded LayerRecord selected by handle or name	DWG and DXF read on all supported hosts; handle is preferred
create_layer	drawing_path, name	properties	Layer create evidence with the persisted layer record	Native-DXF write on all supported hosts; Windows-only DWG write through accoreconsole
update_layer	drawing_path, properties	handle, name, expected_handle, expected_name	Layer update evidence with the persisted layer record	Property mutation with stale-state guards
rename_layer	drawing_path, new_name	handle, name, expected_handle, expected_name	Layer rename evidence with the persisted layer record	Rejects protected and xref-dependent layers
delete_layer	drawing_path	handle, name, expected_handle, expected_name	Layer delete evidence	Rejects protected, current, dependent, content-bearing, and unverified-reference layers
list_xrefs	drawing_path	none	JSON array of complete XrefAttachmentRecord objects	DWG and DXF read on all supported hosts; direct attachments only
get_xref	drawing_path	handle, name	One complete XrefAttachmentRecord	DWG and DXF read on all supported hosts; handle is preferred
attach_xref	drawing_path, xref_path, reference_type	name, search_paths, placement, unit_assumptions	Attached evidence with persisted attachment and initial instance	Windows with AutoCAD for DWG and DXF hosts; source files unchanged
update_xref	drawing_path, properties	handle, name, expected_handle, expected_name, layer_reconciliation, unit_assumptions, search_paths	Updated evidence with persisted attachment and conditional reconciliation	Windows with AutoCAD for DWG and DXF hosts; source files unchanged
detach_xref	drawing_path	handle, name, expected_handle, expected_name, expected_instance_count, expected_instance_handles	Detached evidence with pre-detach attachment and deleted instance handles	Destructive Windows AutoCAD mutation; source files unchanged
list_xref_instances	drawing_path	attachment_handle, attachment_name, owner_handle, owner_type, owner_name, layer_handle, layer_name, visibility	JSON array of complete XrefInstanceRecord objects	DWG and DXF read on all supported hosts; exact filters only
get_xref_instance	drawing_path, handle	none	One complete XrefInstanceRecord	DWG and DXF read on all supported hosts; persisted handle required
insert_xref_instance	drawing_path	attachment_handle, attachment_name, expected_attachment_handle, placement, unit_assumptions	Inserted evidence with persisted instance	Windows with AutoCAD for DWG and DXF hosts; source files unchanged
update_xref_instance	drawing_path, handle, properties	expected_attachment_handle, expected_owner_handle	Updated evidence with persisted instance	Windows with AutoCAD for DWG and DXF hosts; owner and attachment cannot change
delete_xref_instance	drawing_path, handle	expected_attachment_handle, expected_owner_handle	Deleted evidence with the pre-delete instance	Destructive Windows AutoCAD mutation; attachment is retained
reload_xref	drawing_path	handle, name, expected_handle, expected_name, search_paths, layer_reconciliation, unit_assumptions	Loaded evidence with persisted attachment and reconciliation	Windows with AutoCAD for DWG and DXF hosts; source files unchanged
unload_xref	drawing_path	handle, name, expected_handle, expected_name	Unloaded evidence with persisted attachment	Windows with AutoCAD for DWG and DXF hosts; idempotent
bind_xref	drawing_path, symbol_strategy, dependency_strategy	handle, name, expected_handle, expected_name, expected_instance_count, expected_instance_handles, search_paths	Bound block, instance, symbol, dependency, and overlay-exclusion mappings	Destructive Windows AutoCAD mutation; source files unchanged
resolve_xref_path	drawing_path	handle, name, search_paths	One XREF path-resolution record	DWG and DXF read on all supported hosts; unresolved state is successful data
list_xref_dependencies	drawing_path	handle, name, search_paths, max_depth, max_nodes	Dependency traversal envelope with limit evidence	DWG and DXF read on all supported hosts; nested identity uses attachment chains
get_drawing	drawing_path	none	One closed drawing summary with availability-tagged saved-header model/paper geometry and current UCS, spaces, resource counts, and current settings	DWG only on all supported hosts; DXF is unavailable for the expanded read surface
list_entities	drawing_path	entity_types, layer, owner_handle, include_invisible, offset, limit	Bounded entity envelope with post-filter total, tagged direct-owner context, reason-bearing bounds/detail, and proven INSERT dynamic linkage	DWG only on all supported hosts; exact filters; limit defaults to 200 and must be 1–1000
get_entity	drawing_path, handle	none	One common entity record with tagged direct-owner context, reason-bearing bounds/detail, and proven INSERT dynamic linkage	DWG only on all supported hosts; persisted handle required
list_block_definitions	drawing_path	none	Deterministic array of expanded block-definition records	DWG only on all supported hosts; includes layout and XREF context
get_block_definition	drawing_path	handle, name	One expanded block-definition record selected by handle or name	DWG only on all supported hosts; selectors are cross-checked when both are supplied
list_block_inserts	drawing_path	none	Deterministic ordinary INSERT/MINSERT array with tagged direct-owner context and proven dynamic linkage	DWG only on all supported hosts; XREF instances are excluded
get_block_insert	drawing_path, handle	none	One ordinary INSERT/MINSERT record with tagged direct-owner context, proven dynamic linkage, placement, and attributes	DWG only on all supported hosts; XREF instances are rejected
list_text	drawing_path	text_types, layer, owner_handle, owner_type, owner_name	Deterministic array of handle-bearing TEXT and MTEXT records with tagged direct-owner context	DWG only on all supported hosts; exact filters and cross-checked owner selector union
get_text	drawing_path, handle	none	One TEXT or MTEXT record with tagged direct-owner context	DWG only on all supported hosts; non-text handles are rejected
get_layout	drawing_path	handle, name	One expanded layout record selected by handle or name	DWG only on all supported hosts; selectors are cross-checked when both are supplied
list_layout_viewports	drawing_path	layout_handle, layout_name	Deterministic array of paper-space viewport records	DWG only on all supported hosts; optional exact layout scope
get_layout_viewport	drawing_path, handle	none	One paper-space viewport record with resolved layout ownership	DWG only on all supported hosts; persisted viewport handle required
list_plot_settings	drawing_path	none	Deterministic array of standalone named plot-setting records	DWG only on all supported hosts; embedded layout settings remain on layouts
get_plot_setting	drawing_path	handle, name	One standalone named plot-setting record	DWG only on all supported hosts; selectors are cross-checked when both are supplied
list_linetypes	drawing_path	none	Deterministic array of expanded linetype records	DWG only on all supported hosts
get_linetype	drawing_path	handle, name	One expanded linetype record	DWG only on all supported hosts; selectors are cross-checked when both are supplied
list_text_styles	drawing_path	none	Deterministic array of expanded text-style records	DWG only on all supported hosts
get_text_style	drawing_path	handle, name	One expanded text-style record	DWG only on all supported hosts; selectors are cross-checked when both are supplied
list_dimension_styles	drawing_path	none	Deterministic array of expanded dimension-style records	DWG only on all supported hosts
get_dimension_style	drawing_path	handle, name	One expanded dimension-style record	DWG only on all supported hosts; selectors are cross-checked when both are supplied
list_named_views	drawing_path	none	Deterministic array of named-view records	DWG only on all supported hosts
get_named_view	drawing_path	handle, name	One named-view record	DWG only on all supported hosts; selectors are cross-checked when both are supplied
list_named_ucs	drawing_path	none	Deterministic array of named UCS records	DWG only on all supported hosts
get_named_ucs	drawing_path	handle, name	One named UCS record	DWG only on all supported hosts; selectors are cross-checked when both are supplied
list_blocks	drawing_path	none	JSON array of user-defined block definitions	DWG and DXF read on all supported hosts
read_title_blocks	drawing_path	attribute_value_mode	JSON array of attributed title-block candidates and values; duplicate tags are returned as arrays and reported as partial structured warnings	DWG and DXF read on all supported hosts; value mode is split by default or arrays
dump_text	drawing_path	none	JSON array of TEXT and MTEXT content	DWG and DXF read on all supported hosts
write_title_block	drawing_path, fields	none	Title-block write evidence with target and attribute counts	Release Windows-only DWG write through accoreconsole; Preview Windows-only AC1032 DWG write through the bounded acadrust preservation oracle; native-DXF write on all supported hosts
list_layouts	drawing_path	none	JSON array of layouts and paper sizes	DWG and DXF read on all supported hosts; run before plotting
plot_to_pdf	drawing_path, layout, output	none	Plot evidence with the output PDF path	Windows only; DWG only; existing file-plotter page setup required

CLI Examples

Each CLI call is one shell-safe line with a single-quoted JSON object and uses the same parameter names as MCP. Examples that supply unit_assumptions assume the corresponding source and host roles are unitless or otherwise assumable. The block shows Release syntax. For a state-changing Preview call, insert --experimental after call; plain Preview calls expose only read-only tools, and Release rejects that flag.

autocad-mcp call list_layers '{"drawing_path":"/abs/project/A101.dwg"}'
autocad-mcp call get_layer '{"drawing_path":"/abs/project/A101.dwg","handle":"10"}'
autocad-mcp call create_layer '{"drawing_path":"/abs/project/A101.dxf","name":"ANNO","properties":{"color_index":3,"locked":true}}'
autocad-mcp call update_layer '{"drawing_path":"/abs/project/A101.dxf","handle":"10","expected_name":"ANNO","properties":{"off":true}}'
autocad-mcp call rename_layer '{"drawing_path":"/abs/project/A101.dxf","handle":"10","expected_name":"ANNO","new_name":"NOTES"}'
autocad-mcp call delete_layer '{"drawing_path":"/abs/project/A101.dxf","handle":"10","expected_name":"NOTES"}'
autocad-mcp call list_xrefs '{"drawing_path":"/abs/project/A101.dwg"}'
autocad-mcp call get_xref '{"drawing_path":"/abs/project/A101.dwg","handle":"2A"}'
autocad-mcp call attach_xref '{"drawing_path":"C:/project/A101.dwg","xref_path":"../refs/site.dwg","name":"SITE","reference_type":"attachment","search_paths":["C:/project/shared"],"unit_assumptions":{"source_units":"millimeters","host_units":"millimeters"}}'
autocad-mcp call update_xref '{"drawing_path":"C:/project/A101.dwg","handle":"2A","expected_handle":"2A","properties":{"xref_path":"../refs/site-r2.dwg"},"search_paths":["C:/project/shared"],"layer_reconciliation":{"mode":"drawing_policy","properties":[]},"unit_assumptions":{"source_units":"millimeters","host_units":"millimeters"}}'
autocad-mcp call detach_xref '{"drawing_path":"C:/project/A101.dwg","handle":"2A","expected_handle":"2A","expected_instance_count":2,"expected_instance_handles":["40","41"]}'