8000 GitHub - LuiccianDev/autocad-mcp: Model Context Protocol (MCP) server & AI Gateway connecting AutoCAD 2027 & Civil 3D with AI agents. · GitHub
[go: up one dir, main page]

Skip to content

About

Model Context Protocol (MCP) server & AI Gateway connecting AutoCAD 2027 & Civil 3D with AI agents.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

AutoCAD MCP — AI Gateway & MCP Server Integration

High-Performance Bidirectional Bridge Connecting AI Agents with Autodesk AutoCAD 2027 & Civil 3D

.NET 10 Python 3.10+ PyPI version uv AutoCAD 2027 MCP Protocol License CI Build Changelog

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.


Technical Documentation & Guides

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 uvx luiccian-autocad-mcp without manual compilation.

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.


Agent Skills & Automation Workflow

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 (INSUNITS = 4), atomic batch geometry (draw_batch_geometry), Civil 3D surfaces/alignments, and non-modal command safety.

Rapid architectural modeling: structural grid axes (ZXW), parametric double-line walls (WW), openings (AD/WD), and automated dimensioning.

OSNAP-independent parametric generation using atomic entmake primitives, metric precision, and institutional layer naming conventions.


System Architecture

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             │
└─────────────────────────────────────────────────────────────┘

Why Gateway and MCP Must Be Used Together

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.


Key Architecture Features

  1. Thread-Safe UI Dispatcher: Never blocks or corrupts the active AutoCAD document; all drawing operations synchronize with the Application.Idle event.
  2. Command Lockout Immunity: Automatically prepends double cancellation sequences \x03\x03 (ESC/Ctrl+C) before commands to clear hung prompts.
  3. 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 atomic entmake.
    • 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 .lsp loader.
    • 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 via DWG 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.
  4. Zero-Secret Token Security: Protected by the X-Gateway-Token HTTP header, configurable through environment variables.
  5. Strict stdout Silence: Ensures complete JSON-RPC framing integrity for STDIO-based MCP clients.

Prerequisites

  • 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.

Build & Installation

1. Clone the Repository

git clone https://github.com/LuiccianDev/autocad-mcp.git
cd autocad-mcp

2. Build Solution in Release Mode

You can use the included PowerShell script or the standard .NET CLI:

.\scripts\build.ps1
# Or manually:
dotnet build AutoCAD_Integration.slnx -c Release

Build 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).

Getting Started

Connect AutoCAD 2027 to your AI assistant in under 2 minutes:

Step 1: Load the Gateway into AutoCAD 2027

  1. Launch AutoCAD 2027 or Autodesk Civil 3D 2027.
  2. Download the pre-built native plugin AutoCAD.Gateway-Release.zip from the latest GitHub Release (or build from source using dotnet build -c Release).
  3. Extract AutoCAD.Gateway.dll and in the AutoCAD command prompt, type:
    NETLOAD
    
  4. Select AutoCAD.Gateway.dll. The AutoCAD command window will confirm:
    >>> AutoCAD AI Gateway Plugin loaded successfully.
    >>> Available commands: AI_START_SERVER, AI_STOP_SERVER, AI_SHOW_CONFIG, AI_SET_TOKEN, AI_GENERATE_TOKEN
    
    (The HTTP listener starts automatically on http://localhost:5055/).

Step 2: Connect the MCP Server to Your AI Client

Primary Option: Zero-Install with uvx (Recommended)

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"
      }
    }
  }
}

Alternative Execution Modes

Option B: Native C# Server (.NET 10)

For environments where native compiled binary performance is preferred:

  1. Download AutoCAD.McpServer-Release.zip from Releases or build via dotnet build AutoCAD_Integration.slnx -c Release.
  2. 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"
      }
    }
  }
}

Option C: Local Python Development (uv run)

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

Configuration (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"
      }
    }
  }
}

MCP Tools Catalog (45 Tools)

1. Inspection, Context & Vision Tools (8)

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.

2. Parametric Geometry & Drawing Tools (8)

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.

3. Advanced Layer Management (3)

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).

4. Measurement, Computational Geometry & Audit (4)

Tool Description
measure_distance Computes 2D/3D distances, coordinate deltas $\Delta X, \Delta Y, \Delta Z$, azimuth, and slope % (local analytical calculation).
calculate_polygon_area Computes area in $m^2$, hectares, perimeter, centroid, and winding order for closed polygons (Gauss algorithm).
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).

5. Execution, Control & AutoLISP (8)

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.

6. Sheet Layouts, Title Blocks & PDF Plotting (5)

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.

7. Autodesk Civil 3D Native Tools (9)

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).

Safe Command Guidelines

  1. Avoid Modal Dialogs: Always prepend interactive commands with _.- (e.g. _.-LAYER instead of LAYER, _.-INSERT instead of INSERT). If AutoCAD opens a Windows modal dialog, the Gateway connection will block until manually closed.
  2. Internationalization: Use the _. command prefix to ensure compatibility across localized AutoCAD versions (Spanish, English, etc.), e.g. _.LINE, _.RECTANG.
  3. Units: Always design and input coordinates in meters.

Community, Governance & Support

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.


Author & Maintainer

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.

License

This project is licensed under the Apache License, Version 2.0 (Copyright 2026 LuiccianDev). See the LICENSE file for full details.

About

Model Context Protocol (MCP) server & AI Gateway connecting AutoCAD 2027 & Civil 3D with AI agents.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0