High-Performance Bidirectional Bridge Connecting AI Agents with Autodesk AutoCAD 2027 & Civil 3D
Getting Started • Architecture • 45 MCP Tools • PyPI Package • Troubleshooting
High-performance, bidirectional bridge connecting Artificial Intelligence Models (Claude, Antigravity, Cursor, ChatGPT, etc.) with Autodesk AutoCAD 2027 & Civil 3D. Features dual MCP client architectures (Python with instant uvx support or native C# on .NET 10) adhering to the Model Context Protocol (MCP v2.2) specification with 45 strongly-typed tools.
To foster adoption, technical transparency, and open-source collaboration, explore our dedicated guides:
|
Step-by-step setup, compilation, and AI client configuration in under 5 minutes. |
Instant runtime with |
|
Official guide for publishing via Trusted Publishing (OIDC) and provenance attestations. |
Concurrency model, UI thread dispatcher, secure queue, and technical diagrams. |
|
Comprehensive technical spec for all 45 tools (schemas, parameters, and returns). |
Decision matrix (Goal → Tool) and chained prompting recipes for AI models. |
|
Resolving NETLOAD, ports, auth tokens, modal dialog freezes, and Civil 3D. |
Strategic vision and release milestones (Civil 3D surfaces, streaming, YQArch). |
|
JSON configuration templates, PowerShell/Bash diagnostic scripts, and AutoLISP routines. |
|
This repository includes specialized Agent Skills in skills/ to guide autonomous AI agents (Antigravity, Claude, Cursor) and contributors in operating, drafting, and testing the CAD environment correctly:
|
Master guide: Gateway handshake, metric enforcement ( |
Rapid architectural modeling: structural grid axes ( |
OSNAP-independent parametric generation using atomic |
The ecosystem uses a decoupled, two-layer architecture ensuring thread safety, high concurrency, and fault tolerance:
┌─────────────────────────────────────────────────────────────┐
│ AI Client (Antigravity / Claude / Cursor) │
└──────────────────────────────┬──────────────────────────────┘
│
│ STDIO (JSON-RPC Protocol)
▼
┌─────────────────────────────────────────────────────────────┐
│ MCP Servers (45 Available Tools) │
│ Option A: Python FastMCP (`uvx luiccian-autocad-mcp`) │
│ Option B: AutoCAD.McpServer (.NET 10 Native) │
│ - DI Container & Tool Registry │
│ - Typed HttpClient with Timeout & Token Authentication │
└──────────────────────────────┬──────────────────────────────┘
│
│ HTTP REST (http://localhost:5055/)
▼
┌─────────────────────────────────────────────────────────────┐
│ AutoCAD.Gateway (.NET 10) │
│ (C# Extension loaded inside acad.exe via NETLOAD) │
│ - HttpGatewayServer (Background Listener Thread) │
│ - RequestRouter (/execute, /context/*, /civil/*) │
│ - AutoCADCommandDispatcher (ConcurrentQueue + Idle Event) │
│ - AutoCADContextReader (Read-only Database Transactions) │
└──────────────────────────────┬──────────────────────────────┘
│
│ Main UI Thread Injection
▼
┌─────────────────────────────────────────────────────────────┐
│ Active AutoCAD 2027 / Civil 3D Session │
└─────────────────────────────────────────────────────────────┘
For an AI model (or autonomous assistant) to operate safely with AutoCAD, both components must be deployed and configured together:
| Component | Ecosystem Role | If used in isolation... |
|---|---|---|
AutoCAD.Gateway (.NET DLL in acad.exe) |
The Executor & Sensor: Directly accesses the AutoCAD DWG database, queries entities/layers, and injects commands safely into the UI thread via Application.Idle. |
Acts as a local REST API. While you can send raw commands via PowerShell or curl, the AI agent would have to write terminal scripts blindly and parse raw JSON responses, wasting context window and risking syntax errors. |
MCP Servers (uvx luiccian-autocad-mcp or .NET 10) |
The AI Translator: Implements the Model Context Protocol (MCP v2.2), exposing 45 typed tools (draw_batch_geometry, draw_line, create_layer, measure_distance, get_longitudinal_profile, etc.) with strict JSON schemas and validation. |
Cannot function alone. Requires an active Gateway connection to interact with a live AutoCAD session. |
Important
Integration Policy: The complete AI copilot experience requires building the solution, loading AutoCAD.Gateway.dll into AutoCAD via NETLOAD, and registering the MCP Server in your AI client configuration (mcp_config.json or claude_desktop_config.json). This enables the AI to inspect context and draw cleanly, parametrically, and bidirectionally without manual PowerShell scripts.
-
Thread-Safe UI Dispatcher: Never blocks or corrupts the active AutoCAD document; all drawing operations synchronize with the
Application.Idleevent. -
Command Lockout Immunity: Automatically prepends double cancellation sequences
\x03\x03(ESC/Ctrl+C) before commands to clear hung prompts. -
45 Specialized MCP Tools:
- Inspection & Vision: Query layers, blocks, entities, text strings, drawing extents, and capture PNG screenshots for multimodal AI analysis.
-
Parametric Geometry: Batch drawing (
draw_batch_geometry), lines, polylines, rectangles, circles, arcs, texts, and block insertions via atomicentmake. - Layer Management: Create and update layers with ACI colors and linetypes; toggle visibility, freeze/thaw, and lock/unlock states without modal dialogs.
-
Measurement & Audit: Compute 2D/3D distances,
$\Delta X$ ,$\Delta Y$ ,$\Delta Z$ , azimuth, slope %, polygon area and perimeter (Gauss algorithm), audit DWG database, and purge unreferenced definitions. -
Execution & AutoLISP: Batch command dispatch (
execute_batch_commands), native CAD commands, dynamic in-memory AutoLISP evaluation, and external.lsploader. -
Layouts & PDF Export: Create sheet layouts, configure sheet sizes (A0–A4), calibrate viewports to metric scale (
1000/Scale XP), insert parametric title blocks, and plot to physical PDF files viaDWG To PDF.pc3. - Autodesk Civil 3D Native: Query TIN surfaces, extract ground elevations (Z), list horizontal alignments, compute station and offset, sample longitudinal profiles, and create alignments or surfaces from point clouds.
-
Zero-Secret Token Security: Protected by the
X-Gateway-TokenHTTP header, configurable through environment variables. -
Strict
stdoutSilence: Ensures complete JSON-RPC framing integrity for STDIO-based MCP clients.
- Operating System: Windows 10/11 (x64).
- SDK: .NET 10 SDK (
dotnet --version>= 10.0.100). - CAD Software: Autodesk AutoCAD 2027 or Autodesk Civil 3D 2027 installed at:
C:\Program Files\Autodesk\AutoCAD 2027\. - Python (Optional for Python MCP Server): Python 3.10+ or
uv.
git clone https://github.com/LuiccianDev/autocad-mcp.git
cd autocad-mcpYou can use the included PowerShell script or the standard .NET CLI:
.\scripts\build.ps1
# Or manually:
dotnet build AutoCAD_Integration.slnx -c ReleaseBuild outputs:
AutoCAD.Gateway\bin\Release\net10.0-windows\AutoCAD.Gateway.dll(Native AutoCAD Extension).AutoCAD.McpServer\bin\Release\net10.0\AutoCAD.McpServer.dll(Portable .NET MCP Server).AutoCAD.McpServer\bin\Release\net10.0\AutoCAD.McpServer.exe(Windows Executable).
Connect AutoCAD 2027 to your AI assistant in under 2 minutes:
- Launch AutoCAD 2027 or Autodesk Civil 3D 2027.
- Download the pre-built native plugin
AutoCAD.Gateway-Release.zipfrom the latest GitHub Release (or build from source usingdotnet build -c Release). - Extract
AutoCAD.Gateway.dlland in the AutoCAD command prompt, type:NETLOAD - Select
AutoCAD.Gateway.dll. The AutoCAD command window will confirm:(The HTTP listener starts automatically on>>> AutoCAD AI Gateway Plugin loaded successfully. >>> Available commands: AI_START_SERVER, AI_STOP_SERVER, AI_SHOW_CONFIG, AI_SET_TOKEN, AI_GENERATE_TOKENhttp://localhost:5055/).
No local compilation or manual environment setup required if you have uv. The server runs the official PyPI package luiccian-autocad-mcp on demand with full 45-tool parity:
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"autocad-mcp": {
"command": "uvx",
"args": ["luiccian-autocad-mcp"],
"env": {
"AUTOCAD_GATEWAY_PORT": "5055",
"AUTOCAD_GATEWAY_TOKEN": "luiccian-autocad-token-2027"
}
}
}
}Antigravity / Cursor / VS Code (mcp_config.json):
{
"mcpServers": {
"autocad-mcp": {
"command": "uvx",
"args": ["luiccian-autocad-mcp"],
"env": {
"AUTOCAD_GATEWAY_PORT": "5055",
"AUTOCAD_GATEWAY_TOKEN": "luiccian-autocad-token-2027"
}
}
}
}For environments where native compiled binary performance is preferred:
- Download
AutoCAD.McpServer-Release.zipfrom Releases or build viadotnet build AutoCAD_Integration.slnx -c Release. - Configure your AI client:
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"autocad-mcp": {
"command": "dotnet",
"args": [
"C:\\Path\\To\\autocad-mcp\\AutoCAD.McpServer\\bin\\Release\\net10.0\\AutoCAD.McpServer.dll"
],
"env": {
"AUTOCAD_GATEWAY_TOKEN": "luiccian-autocad-token-2027"
}
}
}
}Antigravity / Cursor / VS Code (mcp_config.json):
{
"mcpServers": {
"autocad-mcp": {
"command": "dotnet",
"args": [
"${workspaceFolder}/AutoCAD.McpServer/bin/Release/net10.0/AutoCAD.McpServer.dll"
],
"env": {
"AUTOCAD_GATEWAY_TOKEN": "luiccian-autocad-token-2027"
}
}
}
}For contributors modifying Python tools directly from a cloned workspace:
git clone https://github.com/LuiccianDev/autocad-mcp.git
cd autocad-mcp/AutoCAD.McpPython
uv run autocad-mcpConfiguration (mcp_config.json):
{
"mcpServers": {
"autocad-mcp": {
"command": "uv",
"args": [
"--directory",
"${workspaceFolder}/AutoCAD.McpPython",
"run",
"autocad-mcp"
],
"env": {
"AUTOCAD_GATEWAY_PORT": "5055",
"AUTOCAD_GATEWAY_TOKEN": "luiccian-autocad-token-2027"
}
}
}
}| Tool | Description |
|---|---|
get_drawing_info |
Retrieves drawing name, DWG path, read-only status, and configured drawing units. |
read_layers |
Returns complete layer catalog with ACI color, visibility, freeze, and lock status. |
read_objects |
Summarizes existing entities grouped by object type and count. |
get_drawing_extents |
Queries drawing bounding box coordinates (ExtMin, ExtMax) and metric delta. |
read_texts |
Searches and lists text content from DBText and MText entities with (X, Y) coordinates. |
list_available_blocks |
Lists block definition names available in the drawing. |
read_selection |
Returns count and summary of currently selected objects in AutoCAD. |
capture_screen |
Eyes for AI: Captures a PNG screenshot of the active AutoCAD viewport for visual reasoning. |
| Tool | Description |
|---|---|
draw_batch_geometry |
Batch Optimized: Draws entire floor plans and multiple entities (lines, rects, circles, polylines, texts) in one atomic call, slashing tokens and latency by 95%. |
draw_line |
Draws a 3D straight line segment between two metric points (preserves active layer, independent of OSNAP). |
draw_polyline |
Draws a 2D polyline (LWPOLYLINE), open or closed, from an array of metric vertices. |
draw_rectangle |
Draws a closed polyline rectangle defined by two diagonal corner points. |
draw_circle |
Draws a parametric circle given center point (X, Y) and radius in meters. |
draw_arc |
Draws a counterclockwise circular arc given center point, radius, and start/end angles in degrees. |
insert_text |
Inserts single-line text (DBText) in model space with metric height and rotation. |
insert_block |
Inserts an existing block reference with uniform scale and rotation angle. |
| Tool | Description |
|---|---|
create_layer |
Creates or updates a layer with ACI color (1–255), linetype, and description (no modal dialogs). |
set_current_layer |
Sets the active working layer (CLAYER). |
set_layer_state |
Controls layer visibility (on/off), freeze (freeze/thaw), or lock (lock/unlock). |
| Tool | Description |
|---|---|
measure_distance |
Computes 2D/3D distances, coordinate deltas |
calculate_polygon_area |
Computes area in |
clean_and_purge_drawing |
Purges unreferenced definitions in two passes (_.-PURGE) and audits/repairs DWG database (_.AUDIT). |
regen_all |
Forces complete regeneration across all viewports (_.REGENALL). |
| Tool | Description |
|---|---|
ping_autocad_gateway |
Performs an HTTP connectivity check against port 5055. |
execute_batch_commands |
Batch Command Dispatcher: Dispatches a sequential list of AutoCAD commands/macros in a single request. |
execute_command |
Injects non-modal text commands (_.-) with guaranteed \n terminators. |
execute_lisp |
Evaluates dynamic in-memory AutoLISP expressions (e.g. entmake, variables, custom functions). |
load_lisp_file |
Loads and executes an external .lsp file from disk via (load ...). |
configure_drawing_environment |
Configures mandatory metric standard: INSUNITS = 4 (meters), MEASUREMENT = 1. |
zoom_extents |
Triggers a full extents zoom (_.ZOOM E) in the active viewport. |
save_drawing |
Saves the active DWG drawing file via _.QSAVE. |
| Tool | Description |
|---|---|
create_layout |
Creates a new paper space layout tab and sets it active. |
configure_layout_sheet |
Configures layout paper size (A0 to A4), virtual plotter DWG To PDF.pc3, and plot style monochrome.ctb. |
create_viewport |
Creates a paper space viewport calibrated to exact metric scale (1000/Scale XP) centered on (X, Y). |
insert_parametric_titleblock |
Draws a technical title block in paper space with parametric fields (Title, Drawing Number, Sheet, Scale, Designer, Date). |
export_pdf |
Plots and generates a physical PDF file from a layout using DWG To PDF.pc3. |
| Tool | Description |
|---|---|
check_civil3d_status |
Verifies whether Civil 3D runtime is active and managed API (AeccDbMgd) is accessible. |
list_civil3d_surfaces |
Returns existing TIN surfaces with min/max elevation and triangle count. |
get_surface_elevation |
Returns exact ground surface elevation (Z) at any metric (X, Y) coordinate. |
list_civil3d_alignments |
Returns horizontal alignments (Alignment), length, and station ranges. |
get_alignment_station_offset |
Computes station (chainage) and lateral offset (+ right / - left) for a point (X, Y). |
get_station_coordinate |
Computes metric (X, Y) coordinates given a station and lateral offset. |
get_longitudinal_profile |
Samples stations, coordinates, and ground elevations at regular intervals along an alignment. |
create_civil3d_alignment |
Parametrically creates a horizontal alignment from PIs with fixed-radius tangent curves. |
create_civil3d_surface |
Parametrically builds a topographic TIN surface from a point cloud array (X, Y, Z). |
- Avoid Modal Dialogs: Always prepend interactive commands with
_.-(e.g._.-LAYERinstead ofLAYER,_.-INSERTinstead ofINSERT). If AutoCAD opens a Windows modal dialog, the Gateway connection will block until manually closed. - Internationalization: Use the
_.command prefix to ensure compatibility across localized AutoCAD versions (Spanish, English, etc.), e.g._.LINE,_.RECTANG. - Units: Always design and input coordinates in meters.
This project is built to serve as an open standard maintained by and for the CAD developer, civil engineering, and AI community.
|
Standards for an inclusive and professional technical environment. |
Architecture requirements, PR flows, and code style standards. |
Responsible disclosure protocol and Gateway authentication model. |
|
Where to ask architecture questions, request tools, or report issues. |
Chronological breakdown of features, improvements, and releases. |
Open-source permissive terms, commercial rights, and liability limits. |
Conceived, architected, and developed by:
- Luiccian (@LuiccianDev)
- Creator and Lead Architect of AutoCAD MCP Server & Gateway (
autocad-mcp) and Vulcan MCP Server (vulcan-mcp). - Specialist in Artificial Intelligence integrations for engineering, mining, surveying, and AEC automation.
- Creator and Lead Architect of AutoCAD MCP Server & Gateway (
This project is licensed under the Apache License, Version 2.0 (Copyright 2026 LuiccianDev). See the LICENSE file for full details.