dwg-mcp

English · Tiếng Việt · 简体中文 · 日本語

Drawing Translation Should Not Stop At Manual Copy-Paste

Construction and engineering drawings carry dense technical text — specifications, notes, dimensions, material callouts, legends. When those drawings arrive in a foreign language, translation is not optional. It is required before the project team can act.

The usual workflow is painful: select text one entity at a time, copy to a translator, paste back, fix the font (because SHX fonts cannot render Vietnamese or CJK), adjust the height, hope nothing shifted. Multiply by hundreds of text fragments per sheet, dozens of sheets per project.

dwg-mcp exists to compress that loop into two steps: select the text, let the AI agent read, translate, and rewrite it in place — with correct font, correct height, correct spatial grouping, and a single undo.

What dwg-mcp Is

dwg-mcp is a local MCP gateway for Autodesk AutoCAD 2022-2027 DWG workflows.

It has two parts:

• Bimwright.Dwg.Server: a .NET 8 MCP server launched by Claude Code, Cursor, OpenCode, or another stdio MCP client.
• Bimwright.Dwg.Plugin: version-specific AutoCAD add-in shells loaded inside AutoCAD, executing commands against the drawing database.

The agent talks MCP. The server talks to the plugin over a local wire: TCP NDJSON for AutoCAD 2022–2024, and a Named Pipe (loopback, avoids the firewall prompt) for 2025–2027. The plugin talks to the AutoCAD .NET API.

Everything stays on your machine.

Why It Matters

AI agents make it possible to describe "translate all selected text to Vietnamese" and have it happen — correctly — in the drawing. But intent alone is not enough. AutoCAD text operations require understanding spatial layout, fragment grouping, font limitations, MText vs DBText, block references, and height scaling.

dwg-mcp handles that complexity:

• Spatial clustering groups fragmented text into logical sentences (by block, row, column, paragraph).
• Automatic font handling creates a Unicode-capable text style and applies it — no more SHX question marks.
• Height scaling compensates for the different visual density of Latin vs CJK text.
• MText conversion upgrades single-line fragments into multi-line text when safe.
• Single undo wraps each operation in a transaction.

Usage Evidence

220 completed tool calls over 19 days of active use on production construction drawings. 98.2% success rate.

Architecture

+---------------------------+
| AI Client                 |
| Claude / Cursor / OpenCode|
+---------------------------+
              |
              | stdio MCP
              v
+---------------------------+
| Bimwright.Dwg.Server      |
| .NET 8 / C#               |
+---------------------------+
              |
               | TCP NDJSON (2022-2024) / Named Pipe (2025-2027)
               | token auth
              v
+---------------------------+
| Bimwright.Dwg.Plugin      |
| AutoCAD 2022-2027 shells |
+---------------------------+
              |
              | LockDocument()
              v
+---------------------------+
| AutoCAD .NET API          |
| ObjectARX 2022-2027       |
+---------------------------+

See ARCHITECTURE.md for threading, discovery, and auth details.

Install

Download the client setup ZIP from GitHub Releases. It includes a self-contained MCP server and the AutoCAD plugin years that were compiled for that release (see manifest.json inside the ZIP). This machine’s v1.0.0 ZIP ships 2024 and 2027. Other years: build the plugin from source with that year’s AutoCAD SDK.

$tag = (Invoke-RestMethod https://api.github.com/repos/bimwright/dwg-mcp/releases/latest).tag_name
$zip = "$env:TEMP\DwgMcp.Setup-$tag-win-x64.zip"
$dir = "$env:TEMP\DwgMcp.Setup-$tag-win-x64"
Invoke-WebRequest "https://github.com/bimwright/dwg-mcp/releases/download/$tag/DwgMcp.Setup-$tag-win-x64.zip" -OutFile $zip
Expand-Archive $zip -DestinationPath $dir -Force

powershell -ExecutionPolicy Bypass -File "$dir\install.ps1" -WhatIf
powershell -ExecutionPolicy Bypass -File "$dir\install.ps1"

The installer:

• detects installed AutoCAD years (a year counts when its acad.exe exists) and installs every packed year that matches; -Years 2024,2027 forces an explicit list;
• requires AutoCAD to be closed, and rolls every change back on error;
• deploys %APPDATA%\Autodesk\ApplicationPlugins\Bimwright.Dwg.bundle\ (removing stale bundles with the same ProductCode) and the server at the fixed path %LOCALAPPDATA%\Bimwright\Dwg\server\current\dwg-mcp.exe;
• seeds %LOCALAPPDATA%\Bimwright\Dwg\dwgmcp.config.json with "toolsets": ["all"] on a fresh install — an existing toolsets key is kept;
• wires every detected MCP client by default (-Client <names> limits it, -Client none skips it); config edits keep JSONC comments and get a <config>.bak backup. The entry name is dwg-mcp.

Restart AutoCAD, then restart wired MCP clients to load dwg-mcp.

Updating: close AutoCAD and run the new ZIP's install.ps1 the same way — no need to uninstall first. The server path stays server\current\, so clients only need a restart.

Uninstall: uninstall.ps1 removes the bundle, the server copies, discovery files and caches under %LOCALAPPDATA%\Bimwright\Dwg\ (settings, config, logs and captures are kept; -Purge removes those too). Client config entries are never touched — remove the dwg-mcp entry yourself, or run install.ps1 -Uninstall -Client <names> first.

Do not dotnet tool install -g Bimwright.Dwg.Server — that package is not the supported client install.

Developer (local SDK): dotnet build the year you have, then pwsh scripts/install.ps1 -Years 2024 from the repo (copies that year’s bin output). NETLOAD remains available for Debug DLLs.

3. Wire up your MCP client

The installer already did this for detected clients (Step Client : lines in its summary). To wire by hand, add to your MCP client config (e.g., .mcp.json):

{
  "mcpServers": {
    "dwg-mcp": {
      "command": "C:\\Users\\<user>\\AppData\\Local\\Bimwright\\Dwg\\server\\current\\dwg-mcp.exe",
      "args": []
    }
  }
}

Pin a specific AutoCAD instance with a 4-digit target year:

{
  "mcpServers": {
    "dwg-mcp": {
      "command": "C:\\Users\\<user>\\AppData\\Local\\Bimwright\\Dwg\\server\\current\\dwg-mcp.exe",
      "args": ["--target", "2024"]
    }
  }
}

Use --read-only to strip write-capable toolsets (query/view/meta routing remain as configured). Use --toolsets all or an explicit list that includes the defaults you need (a custom list replaces the default set — e.g. query,modify,meta,view,annotation). Env: BIMWRIGHT_DWG_TOOLSETS=….

dwg_send_code is available by default via meta; MCPDISABLECODE disables C# execution for the session and MCPENABLECODE re-enables it. dwg_run_lisp remains registered for compatibility but refuses every request at both server and plugin. This build has no isolated LISP executor or approved-script trust mechanism. --read-only removes both tools.

Activity toasts are on by default. Finished tool calls update one card in the AutoCAD window corner: success, failure and capture counts. The latest result is the counter tooltip. The card's left edge is a vertical gradient, and the footer shows AutoCAD {year}. Click the card to open an allowlisted capture from the latest result; the card then closes. The close button only closes the card and stays transparent on hover. The card hides after an idle interval (10, 20, 30 or 60 seconds, default 20) and pauses while the pointer is over it. While AutoCAD is minimized or a modal dialog is open, counts are kept and the card is shown once when the frame is usable again. Toggle with MCPTOAST or open MCPSETTINGS. enableToast and toastIdleSeconds are stored in %LOCALAPPDATA%\Bimwright\Dwg\settings.json. BIMWRIGHT_ENABLE_TOAST=0 re-applies at every launch while set. Show branding is off until turned on in Settings and lasts only for the current AutoCAD session. Toasts never steal keyboard focus.

dwg_send_code accepts inline synchronous snippets only: async/await and #load directives are rejected before execution. Keep AutoCAD API calls on the calling thread; do not offload them to Task.Run or other threads. Return JSON-safe DTOs; AutoCAD/COM objects are rejected even when nested. LISP inspection is available through dwg_inspect_lisp: sources over 2,000,000 characters are reported uninspectable/dangerous, and the 200-finding display cap does not stop severity detection. Regex matching has a timeout; timed-out scans are reported as incomplete/dangerous, never clean.

Tools

Default startup exposes 41 tools: query (including dwg_inspect_lisp), modify, meta (including dwg_send_code/dwg_run_lisp), view, and default-on dwg_capture_view_image. Optional ToolBaker, annotation, block, dimension, export, and drawing toolsets, enabled through --toolsets, bring the backed MCP surface to 65 tools. The registered counts include dwg_run_lisp, which only returns a refusal; no scan verdict authorizes execution.

General CAD tools operate on the current active document in the selected AutoCAD target. Entity inputs and returned entity IDs use AutoCAD hex handles, such as 7F5AD, returned by selection, creation, or property tools. Creation, copy, offset, and modify responses identify generated or modified entities by hex handle.

Plan 2 query expansion is model-space only: dwg_query_entities, dwg_count_entities, dwg_select_by_layer, and dwg_select_by_type scan model space, not paper-space/layout entities. dwg_select_by_layer and dwg_select_by_type return handle lists for the caller; they do not change AutoCAD's pickfirst selection.

Visual reading: capture → inspect the image → choose a region → dwg_inspect_view_region → inspect again. Keep ancestor IDs and use dwg_restore_view to return to the overview. Source history lasts 30 minutes / 64 captures in one AutoCAD process. Region navigation initially supports one top-down, unrotated, orthographic model-space viewport; unsupported or stale sources are refused. Capture responses now include an MCP image block (8 MiB limit) alongside the existing JSON text. These tools change the visible camera and save images, including under --read-only; they do not edit geometry or save DWG. Installed-host acceptance is pending. See workflow, compatibility and acceptance.

Optional ToolBaker tools are exposed when the toolbaker toolset is enabled:

Optional Annotation tools are exposed when the annotation toolset is enabled:

Optional Block tools are exposed when the block toolset is enabled:

Optional Dimension tools are exposed when the dimension toolset is enabled:

Optional Export tools are exposed when the export toolset is enabled:

Optional Drawing tools are exposed when the drawing toolset is enabled:

Output Path Policy

All export operations are strictly guarded by a path policy that enforces:

• Output paths must be absolute.
• File extensions must match the specific tool (e.g., .dxf for DXF export).
• Existing files are not overwritten unless overwrite_existing=true is explicitly provided.
• Writing to the repository root directory is rejected unless allow_repo_output=true is set.

Optional Toolsets and Read-Only Behavior

By default, only query, modify, meta, and view toolsets are enabled. You can opt-in to others using the --toolsets flag (e.g., --toolsets all or --toolsets query,modify,meta,view,annotation,block,dimension,export,drawing).

• Read-Only Mode (--read-only): When read-only mode is active, all write-capable toolsets (modify, code, annotation, dimension, export, and drawing write tools) are completely disabled.
• Block Toolset Split: The block toolset is split into read-only and write-capable tools. If --read-only is active, dwg_list_blocks and dwg_get_block_attributes are still available (safe read inspection), but the mutation/creation tools (dwg_insert_block, dwg_set_block_attributes, dwg_explode_block) are stripped.
• View and Read-Only: The view toolset stays registered in read-only mode (zoom tools and dwg_capture_view_image). Capture is marked read-only at the MCP schema level but still writes an image file under the path policy — treat paths carefully under --read-only.
• Drawing Operations and Read-Only: The drawing toolset retains dwg_get_variables in read-only mode, but strips dwg_set_system_variable, dwg_save_drawing, and dwg_purge_drawing.
• Deferred Angular Dimensions: Note that only linear, aligned, radial, and diametric dimension types are currently supported. Angular dimensions are deferred and not yet implemented.
• Native View Capture: dwg_capture_view_image uses AutoCAD's Document.CapturePreviewImage API, with no desktop automation or DWG save. It rejects an active command or a document/camera change during capture. Optional expected_document_fingerprint binds a subsequent capture to a prior result. Save the returned metadata alongside the image for a reading atlas; the tool itself writes only the image. Native output dimensions may differ slightly from the requested size. Camera metadata describes the active viewport, not a universal pixel-to-world mapping for tiled views or paper layouts. See capture contract and validation.
• Deferred File Export Tools: dwg_export_pdf and dwg_export_image remain deferred; viewport capture does not configure or validate plotting.

Manual smoke checklist

In a scratch DWG:

1. Run dwg_get_drawing_info.
2. Run dwg_list_layers.
3. Create BIMWRIGHT_TEST with dwg_create_layer.
4. Create a point, polyline, rectangle, arc, and ellipse on BIMWRIGHT_TEST with dwg_create_point, dwg_create_polyline, dwg_create_rectangle, dwg_create_arc, and dwg_create_ellipse; record the returned hex handles and reserve one curve, such as the arc or ellipse, for color and offset checks.
5. Query, count, and select those entities by layer and type with dwg_query_entities, dwg_count_entities, dwg_select_by_layer, and dwg_select_by_type; confirm select tools return handle lists and do not change pickfirst selection.
6. Move, rotate, and scale non-reserved scratch entities with dwg_move_entities, dwg_rotate_entities, and dwg_scale_entities.
7. Copy one non-reserved scratch entity with dwg_copy_entities, then erase only that disposable copied temp entity with dwg_erase_entities.
8. Change color on the reserved curve with dwg_change_color, then offset that curve with dwg_offset_entities and confirm the returned generated handles are hex handles.
9. Confirm the existing text translation workflow still works: select scratch text, run dwg_get_selected_texts, then rewrite it with dwg_translate_and_rewrite.

Optional smoke — annotation / block / dimension

Enable the optional toolsets first (--toolsets … or --toolsets all). On a scratch DWG:

1. Create text, mtext, leader, and table in a scratch DWG with dwg_create_text, dwg_create_mtext, dwg_create_leader, and dwg_create_table.
2. List block definitions with dwg_list_blocks.
3. Insert a known block from the drawing or from an absolute external DWG path with dwg_insert_block.
4. Get and set block attributes with dwg_get_block_attributes and dwg_set_block_attributes.
5. Explode a block reference with dwg_explode_block.
6. Create linear, aligned, radial, and diameter dimensions with dwg_create_linear_dimension, dwg_create_aligned_dimension, dwg_create_radial_dimension, and dwg_create_diameter_dimension, confirming linear projected-distance validation succeeds/rejects as expected.

Optional smoke — view / export / drawing

With view, export, and drawing toolsets enabled (as needed):

1. Run dwg_zoom_extents.
2. Run dwg_zoom_window with coordinates.
3. Zoom to an entity with dwg_zoom_to_entity using a recorded hex handle.
4. Read drawing variables with dwg_get_variables.
5. Export drawing to dxf with dwg_export_dxf.
6. Run dwg_purge_drawing with dry_run=true, then with confirm=true (on a copied/disposable DWG only).
7. Run dwg_save_drawing with confirm=true (on a copied/disposable DWG only).

Migration from 0.1.x tool names

MCP tool names now use the dwg_ prefix. Raw plugin command names remain internal wire commands.

Standard Workflow

1. User selects text entities in AutoCAD
2. Agent calls dwg_get_selected_texts -> receives clustered text groups
3. Agent translates each cluster
4. Agent calls dwg_translate_and_rewrite([{id, new_text}, ...])
   Tool handles: anchor, delete, MText, font style, height. Done.
5. User runs REGEN if needed

Two steps from the agent's perspective: read, then write.

Supported AutoCAD Versions

The server and tests can pass without every AutoCAD shell being release-built. Shipping an AutoCAD year requires building that shell on a prepared machine with the matching Autodesk managed assemblies.

Security

dwg_send_code executes arbitrary C# with full access to AutoCAD and the local filesystem; it is for trusted agents, not a sandbox. dwg_run_lisp is blocked regardless of input, scanner verdict or MCPENABLECODE. No LISP wrapper is created or queued, and no trusted path or SECURELOAD setting is changed. Do not bypass a LISP refusal through C#, batch or ToolBaker. dwg_inspect_lisp is static triage, not antivirus or machine-wide malware protection; clean means no known pattern matched, not safe. All reports set execution_authorized=false and safety_assured=false. Update both server and plugin and restart their processes to apply the restriction; old binaries retain their old behavior.

The security model relies on:

• Local-only transport — TCP on 127.0.0.1 for AutoCAD 2022–2024, loopback Named Pipe for 2025–2027, no remote access.
• Per-session auth token — rotates on each plugin start, verified per request.
• Session kill-switch — MCPDISABLECODE / MCPENABLECODE control dwg_send_code. LISP remains blocked even after enabling code or restarting the listener.
• Timeout boundary — script execution runs inline on the document-lock thread with cooperative 30s cancellation.
• Trusted agent assumption — only use with MCP clients you control.

Do not expose the plugin port to the network.

Project Structure

dwg-mcp/
├── src/
│   ├── Bimwright.Dwg.sln
│   ├── server/            # .NET 8 MCP server (global tool)
│   ├── shared/            # Handlers, clustering, rewriting, unicode
│   ├── plugin-acad22/     # AutoCAD 2022 shell (.NET 4.8)
│   ├── plugin-acad23/     # AutoCAD 2023 shell (.NET 4.8)
│   ├── plugin-acad24/     # AutoCAD 2024 shell (.NET 4.8)
│   ├── plugin-acad25/     # AutoCAD 2025 shell (.NET 8)
│   ├── plugin-acad26/     # AutoCAD 2026 shell (.NET 8)
│   └── plugin-acad27/     # AutoCAD 2027 shell (.NET 10)
├── tests/                 # xUnit
├── scripts/               # install/uninstall PowerShell
├── lib/acad24/            # Notes only; Autodesk DLLs are never committed
└── .github/workflows/     # CI

The bimwright family

Open-source tools connecting AI assistants to BIM and CAD applications.

The name bimwright combines BIM with wright, an old word for a maker or builder—as in shipwright.

• rvt-mcp — Autodesk® Revit®
• dwg-mcp — Autodesk® AutoCAD®
• nwd-mcp — Autodesk® Navisworks®
• ipt-mcp — Autodesk® Inventor®
• bim-wiki — Vietnamese-first BIM knowledge base

Disclaimer

AutoCAD and Autodesk are registered trademarks of Autodesk, Inc. bimwright is an independent open-source project and is not affiliated with, sponsored by, or endorsed by Autodesk, Inc.

License

Apache License 2.0

Third-party notices: THIRD_PARTY_NOTICES.md