Civil3D-mcp

<div align="center"> <img src="./image/civil3d_dynamic_mcp_blueprint/dffc9d11-a9c7-4794-bf73-ff1a39c72e3a.jpg" alt="Civil3D-MCP dynamic blueprint" width="420" /> <h1>Civil3D-MCP Server</h1> <p><strong>Connect Claude, Cursor, Cline, and other MCP clients directly to a live Autodesk Civil 3D drawing.</strong></p> <p>Node.js MCP server + native Civil 3D plugin + workflow automation for grading, hydrology, plan production, QC, and data shortcuts.</p>

<p> <a href="#quick-start">Quick Start</a> • <a href="#autodesk-help-in-chat">Autodesk Help</a> • <a href="#installation">Installation</a> • <a href="./docs/DEPLOYMENT.md">Deployment</a> • <a href="./docs/tools.generated.md">Generated Tool Reference</a> </p> </div>

---

What Is This?

Civil3D-MCP bridges AI assistants (Claude, Cline, Cursor, etc.) to a live, open Civil 3D drawing using the Model Context Protocol. Give Claude your design brief — it reads your drawing, runs calculations, and makes changes in real time.

MCP client  <-- stdio ----------->  civil3d-mcp (Node.js)
HTTP client <-- HTTP :3000 ------>  civil3d-mcp (Node.js)
civil3d-mcp <-- JSON-RPC/TCP :8080 --> Civil3DMcpPlugin.dll --> Civil 3D 2026 API

This is the MCP server (TypeScript). You also need the Civil 3D .NET plugin — see Installation.

What Changed Recently

• Production-ready host execution now includes bounded queues and jobs, cancellation, idempotency, structured telemetry, readiness endpoints, and observable rotating plugin logs.
• New: civil3d_help searches the locally installed Autodesk Civil 3D help, returns cited topics with screenshots, and surfaces matching tutorial videos in chat.
• The default MCP surface is compact: 34 public tools cover every domain. The complete 219-tool surface can be enabled when a client needs specialized aliases.
• Native workflow handlers cover major QC, grading, hydrology, plan-production, and data-shortcut flows instead of relying only on client-side orchestration.
• Claude Code can be registered with a single project-scoped command that installs dependencies, builds the Node server, and writes the repo .mcp.json entry.
• Claude Desktop now has a self-contained MCPB installer plus a legacy DXT compatibility artifact, generated with npm run package:claude.
• The release-checked inventory is generated from the runtime manifest at docs/tools.generated.md.

---

Autodesk Help in Chat

Agents can now answer Civil 3D how-to questions from the Autodesk Offline Help installed on the user's machine. The civil3d_help tool auto-discovers Civil 3D help under Program Files, builds a local search index, and returns:

• cleaned, version-matched Autodesk topic text with a canonical citation;
• useful screenshots and diagrams directly in the chat response;
• the best matching Autodesk tutorial video as a player resource;
• a direct MP4 link when the chat client cannot embed the player.

For example, an agent can search for grading guidance:

{
  "action": "search",
  "query": "how do I create grading criteria?",
  "version": "2026"
}

Or request only matching videos:

{
  "action": "search_videos",
  "query": "create grading criteria",
  "maxVideos": 2
}

The bundled 2026 catalog currently contains 47 Civil 3D tutorial videos. See the Autodesk grading-criteria video for an example. Topic and image retrieval remains local and works without the Civil 3D drawing plugin; Autodesk-hosted video playback requires internet access.

The first topic query creates a compressed cache under %LOCALAPPDATA%\Civil3DMcp\help-index. Later queries reuse that cache and full topic retrieval is effectively immediate. See Local Autodesk help search for configuration and additional examples.

---

Quick Start

If you want the fastest path from clone to a working Claude + Civil 3D setup on Windows:

For Claude Desktop, a release .mcpb is the easiest Node-side installation:

1. Open Settings > Extensions > Advanced settings > Install Extension.
2. Select civil3d-mcp-<version>.mcpb and keep ports 8080 and 3000 unless your local setup uses different ports.
3. Open Civil 3D and load the native plugin with NETLOAD or the APPLOAD Startup Suite.
4. Ask Claude to run civil3d_health.

The extension installs the Node MCP server and its production dependencies. It does not install the native Autodesk plugin. Maintainers can build both the current .mcpb and legacy .dxt files with:

npm install
npm run package:claude

For a source-based or Claude Code installation:

1. Clone and build the Node side:

   git clone https://github.com/Sacred-G/Civil3D-mcp.git
   cd Civil3D-mcp
   npm install
   npm run build
   

2. Build and NETLOAD the Civil 3D plugin:

   dotnet build .\Civil3D-MCP-Plugin\Civil3DMcpPlugin.csproj -c Release `
     /p:Civil3DReferencesPath="C:\Program Files\Autodesk\AutoCAD 2026\C3D"
   

3. Register Claude Code for this repo:

   npm run claude:add
   

4. Open Civil 3D, load the plugin, and start asking for real work:

   • "Audit this drawing before design starts."
   • "Create a grading surface from this feature line."
   • "Delineate the watershed and estimate runoff."
   • "Publish the plan/profile sheets to PDF."

---

Features

• Compact default MCP surface with 34 public tools; all 219 registered routes remain internally callable or available as opt-in aliases
• Local Autodesk help in chat — version-matched topics, screenshots, diagrams, citations, and playable Civil 3D tutorial videos
• Native workflow execution for corridor QC, surface comparison, project startup, grading conversion, plan publish, data shortcuts, and hydrology pipelines
• Full road design pipeline — alignments, profiles, corridors, cross-sections, superelevation
• Surface analysis — elevation bands, slope distribution, aspect, watershed, cut/fill volumes
• Pipe & pressure network design, validation, and hydraulic analysis
• Plan production — sheet sets, Plan/Profile sheets, PDF export
• QC checks — alignment, profile, corridor, surface, pipe network, drawing standards
• Quantity takeoff — earthwork, corridor materials, pipe lengths, parcel areas, CSV export
• Cost estimation — pay items, material costs, construction estimates
• Hydrology — flow path tracing, watershed delineation, Rational Method runoff, time of concentration
• Grading — feature lines, grading groups, grading criteria, surface generation
• COGO/Survey — inverse, traverse, curve solve, survey figures, LandXML import
• Storm & Sanitary Analysis (SSA) integration and detention basin sizing
• Intersection design and corridor target mapping
• Sight distance calculations and AASHTO stopping sight distance checks
• Assembly/subassembly creation and editing

Protected action flow

Destructive, file-writing, import/export, and other non-retryable drawing mutations use a three-step policy flow:

1. Call civil3d_preview_action with the target toolName, action, and the exact parameters to validate the operation and learn whether approval is required.
2. If required, call civil3d_request_approval with the same values. It issues a short-lived, single-use token bound to the active drawing and those exact parameters.
3. Retry the target tool call with approvalToken. Changing the drawing, action, or parameters invalidates the token.

Set CIVIL3D_APPROVAL_MODE=disabled only for isolated local development or test environments; production deployments should retain the default policy.

Canonical tools and aliases

Aliases do not unlock extra Civil 3D capabilities. They are narrower convenience names for actions already available through a canonical domain tool.

| Surface | Exposed tools | How to call an operation | |---|---:|---| | Default MCP client | 34 | Call a canonical domain tool and provide action. | | MCP client with aliases enabled | 219 | Use either canonical tools or specialized alias names. | | HTTP /execute and orchestration | 219 | All registered routes remain internally callable in either mode. |

For example, these calls are equivalent:

{
  "tool": "civil3d_surface",
  "parameters": {
    "action": "volume_calculate",
    "baseSurface": "Existing Ground",
    "comparisonSurface": "Finished Grade"
  }
}

{
  "tool": "civil3d_surface_volume_calculate",
  "parameters": {
    "baseSurface": "Existing Ground",
    "comparisonSurface": "Finished Grade"
  }
}

The compact default is recommended because it gives the model fewer overlapping tool descriptions while preserving every operation. To expose all specialized aliases, set this variable in the environment that starts the MCP server, then restart the client connection:

$env:CIVIL3D_ENABLE_TOOL_ALIASES = "true"
npm run start

For a client-managed server, put the variable in its MCP configuration:

{
  "mcpServers": {
    "civil3d-mcp": {
      "command": "node",
      "args": ["C:/path/to/civil3d-mcp/build/index.js"],
      "env": {
        "CIVIL3D_ENABLE_TOOL_ALIASES": "true"
      }
    }
  }
}

Discover operations through the civil3d://catalog/tools MCP resource or docs/tools.generated.md. Canonical rows list their supported actions; alias rows provide the corresponding convenience name. Approval requirements are identical for canonical and alias calls.

---

Architecture

flowchart LR
    Client["MCP Client\n(Claude / Cline / Cursor)"] <-->|"MCP stdio"| Server["civil3d-mcp\nNode.js"]
    HttpClient["Local HTTP Client"] -->|"HTTP :3000"| Server
    Server <-->|"JSON-RPC/TCP :8080"| Plugin

    subgraph Civil3D ["Autodesk Civil 3D"]
        Plugin["Civil3DMcpPlugin.dll\nTCP Listener"]
        Queue["Bounded Host Queue"]
        Context["ExecuteInCommandContextAsync"]
        Safety["Document Lock + Transaction"]
        API["Civil 3D 2026 .NET API"]

        Plugin --> Queue --> Context --> Safety --> API
    end

Civil 3D database operations execute inside Autodesk command context under a bounded, serialized host gate. Mutations additionally use a document lock and a narrow transaction; callers never mutate a drawing directly from Node.js.

---

Requirements

| Component | Version | |---|---| | Node.js | 18+ | | Civil 3D | 2026 (live validated) | | .NET SDK | 8.0 | | Civil 3D API refs | Licensed local installation or untracked reference directory | | Visual Studio | 2022 recommended |

---

Installation

1 — Build the MCP Server (TypeScript)

git clone https://github.com/Sacred-G/Civil3D-mcp.git
cd Civil3D-mcp
npm install
npm run build

1.5 — One-Line Claude Code Setup

From the repo root on Windows, this project-scoped command adds the MCP server to Claude Code and creates the repo .mcp.json entry automatically:

claude mcp add --scope project --transport stdio civil3d-mcp -- powershell -NoProfile -Executio