sacred-g/civil3d-mcp

---

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    civil3d-mcp (Node.js)
HTTP client   civil3d-mcp (Node.js)
civil3d-mcp  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-.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.

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

---

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 -ExecutionPolicy Bypass -File "$PWD\scripts\claude-bootstrap-and-run.ps1"

The registered launcher will automatically install npm dependencies and build the Node server the first time Claude starts it.

If you want a wrapper that does the install, build, and claude mcp add step for you immediately, run:

npm run claude:add

Useful variants:

npm run claude:add:user
npm run claude:print-add

1.6 — Claude Desktop Extension Package

Current Claude Desktop releases install MCP extensions from .mcpb files. The former DXT format was renamed to MCPB, so the packaging command also emits a byte-for-byte .dxt compatibility copy for older releases:

npm run package:claude

Generated files are written to dist/claude-desktop/ and include SHA-256 checksums. Install the .mcpb from Claude Desktop > Settings > Extensions > Advanced settings > Install Extension. The package exposes installer fields for the Civil 3D host and plugin port, alias mode, log level, and the local HTTP bridge port (default 3000).

2 — Build & Load the C# Plugin

Prerequisites: Civil 3D 2026, .NET 8 SDK, and licensed local Civil 3D managed API assemblies. Autodesk binaries are intentionally not tracked or published by this repository.

$refs = "C:\Program Files\Autodesk\AutoCAD 2026\C3D"
dotnet build .\Civil3D-MCP-Plugin\Civil3DMcpPlugin.csproj -c Release `
  /p:Civil3DReferencesPath="$refs"
# Output: Civil3D-MCP-Plugin\bin\Release\net8.0-windows\Civil3DMcpPlugin.dll

An untracked C_References directory remains the local fallback when Civil3DReferencesPath is omitted.

At minimum, the configured directory must contain:

accoremgd.dll
AcDbMgd.dll
acmgd.dll
AecBaseMgd.dll
AeccDbMgd.dll
AeccPressurePipesMgd.dll

Load into Civil 3D:

Once loaded, three commands are available in the Civil 3D command line:

3 — Configure Your AI Client

Recommended for Claude Code

npm run claude:add

That command registers the bootstrap launcher in Claude Code and keeps the repo self-contained. Use npm run claude:print-add if you want to inspect the exact claude mcp add command without modifying config.

Claude Desktop — install the generated .mcpb package. For source-based development, claude_desktop_config.json remains supported:

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

Claude Code — add via CLI:

claude mcp add --scope project --transport stdio civil3d-mcp -- powershell -NoProfile -ExecutionPolicy Bypass -File "$PWD\scripts\claude-bootstrap-and-run.ps1"

Restart your client. When you see the hammer icon, the MCP connection is live.

For Docker, npm publishing, environment variables, and alternate deployment paths see docs/DEPLOYMENT.md.

---

Example Conversations

“What alignments are in this drawing and how long is each one?” → civil3d_alignment → returns names, station ranges, lengths

“Run a full QC check on the corridor and give me a report.” → civil3d_workflow with action: "corridor_qc_report"

“Trace the flow path from coordinate (5000, 3200) and estimate the peak runoff using the Rational Method.” → civil3d_hydrology with action: "watershed_runoff_workflow"

“Publish the existing Plan Production sheet set to PDF.” → civil3d_workflow with action: "plan_production_publish"

“Size the storm drain network for a 10-year storm and check all pipe velocities.” → civil3d_pipe with action: "size_network", then action: "hydraulic_analysis"

“Calculate cut/fill volumes between the existing ground and proposed surface.” → civil3d_surface with action: "volume_calculate", then action: "volume_report"

---

Tool Reference (217 catalog entries)

The generated, release-checked inventory is docs/tools.generated.md. It includes both canonical tools and specialized aliases. Canonical rows list one or more operations; alias rows show an em dash in the Operations column.

---

Civil 3D Version Compatibility

For startup-suite and autoload registry details, use the version-specific guidance in docs/DEPLOYMENT.md.

---

Environment Variables

The Node MCP server reads the following variables at startup. All are optional; defaults are shown in the Default column and are suitable for a local Civil 3D plus Copilot install.

Plugin connection (Node → Civil 3D plugin)

MCP tool surface and policy

Local Autodesk help search

civil3d_help indexes the Autodesk Offline Help already installed with Civil 3D. It can search engineer phrasing such as “balance cut and fill” or “grading optimization,” return a cleaned Markdown topic, and attach the topic’s useful screenshots and diagrams as MCP image content and civil3d://help/images/... resources. Matching Autodesk tutorial videos are returned as playable civil3d://help/videos/... player resources plus direct MP4 links. Decorative navigation icons are excluded. The drawing plugin does not need to be running for help searches.

The first query builds a compressed local index under %LOCALAPPDATA%\Civil3DMcp\help-index; later starts reuse it until the Autodesk help files change. By default the server discovers folders named Offline Help for Civil 3D - \Help under Program Files and prefers 2026.

The normal search and get_topic actions include the best matching video by default. Use includeVideos: false to suppress it, maxVideos to change the limit, or search_videos for a video-only lookup. Autodesk hosts these Civil 3D videos online, so playback requires internet access even though topic and image search remains local.

Example calls:

{ "action": "search", "query": "how do I use grading optimization?", "version": "2026" }

{ "action": "get_topic", "id": "", "version": "2026", "includeImages": true }

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

HTTP bridge (Copilot / local HTTP clients → Node)

The bridge refuses to start on a non-loopback host unless MCP_HTTP_TOKEN is configured. Docker Compose also requires this token and publishes the bridge on the host loopback interface by default.

Plugin filesystem boundaries

Set these variables in the environment that launches Civil 3D. Roots are semicolon-separated on Windows; every caller-supplied path is canonicalized and must stay beneath an allowed root. If no roots are configured, the plugin uses the current user’s Documents folder.

Import/export tools enforce operation-specific extensions. Generated text and CSV artifacts are written to a temporary file in the destination directory and then atomically moved into place. Existing files are rejected unless the tool call explicitly supplies overwrite: true.

Plugin logging

The native plugin writes a rotating log to %LOCALAPPDATA%\Civil3DMcpPlugin\plugin.log (5 MiB per file, three backups). Set CIVIL3D_MCP_LOG_DIR or CIVIL3D_MCP_LOG_LEVEL before launching Civil 3D to override its directory or minimum level. Plugin health reports logFilePath, fileLoggingHealthy, and fileLoggingError, so a file-write failure cannot remain silent.

HTTP bridge endpoints

Example: enable the shared-secret token

$env:MCP_HTTP_TOKEN = "change-me-to-a-long-random-string"
npm run start

Then from the Copilot or any client:

POST /execute HTTP/1.1
Host: 127.0.0.1:3000
Authorization: Bearer change-me-to-a-long-random-string
Content-Type: application/json

{ "tool": "civil3d_health", "parameters": {} }

Verify the live Civil 3D plugin

With Civil 3D open, a drawing active, and C3DMCPSTATUS reporting port 8080, run this read-only P0 smoke check:

npm run test:live-plugin

The full opt-in host suite creates disposable drawings and covers query, concurrency, document switching, create/undo, temporary volume-surface rollback, delete, job completion, and cancellation. It is guarded to prevent accidental mutations:

$env:CIVIL3D_LIVE_SMOKE_CONFIRM = "DISPOSABLE_DRAWING"
$env:CIVIL3D_LIVE_SMOKE_QC_PATH = "$env:USERPROFILE\Documents\civil3d-mcp-live-qc.txt"
npm run test:live-host

To validate the richer contracts through a spawned production stdio MCP client (typed tools, annotations, progress, resources, health, and drawing context), run:

npm run test:live-mcp-client

For safe-to-retry actions, clients may provide an idempotencyKey (maximum 128 characters). Identical calls share the in-flight or recent result for two minutes; reusing the key with different parameters returns CIVIL3D.CONFLICT.

It calls getCivil3DHealth and retrieves drawing context without mutating the open drawing. Set CIVIL3D_HOST and CIVIL3D_PORT first if the plugin does not use the default loopback endpoint.

---

Troubleshooting

“Cannot connect to Civil 3D plugin”

• Civil 3D must be open with a drawing loaded
• Type C3DMCPSTATUS in Civil 3D — confirm the server shows as running on port 8080
• Check Windows Firewall is not blocking localhost:8080
• If you moved the plugin to a non-default port, set CIVIL3D_PORT on the Node side to match

“No active document”

• Open a .dwg file in Civil 3D before making any tool calls

“Alignment/Surface not found”

• Names are case-insensitive but must otherwise match exactly
• Use the corresponding list tool first (e.g. civil3d_alignment → list action)

“I cannot see a specialized alias in my MCP client”

• This is expected with the recommended compact 34-tool surface
• Call the canonical domain tool with its action, or set CIVIL3D_ENABLE_TOOL_ALIASES=true in the MCP server configuration
• Restart the MCP client connection after changing the environment; changing an unrelated terminal does not update an already-running client-managed server
• Use civil3d://catalog/tools or tools.generated.md to map aliases to canonical actions

Plugin won’t load

• Verify the DLL targets the correct Civil 3D version
• Ensure Civil 3D and Visual Studio are running as the same Windows user (no elevation mismatch)
• Check the DLL path passed to NETLOAD has no spaces or special characters

---

Documentation

---

Contributing

Pull requests are welcome. For major changes, open an issue first to discuss what you’d like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/my-tool)
3. Commit your changes (git commit -m 'Add civil3d_my_tool')
4. Push to the branch (git push origin feature/my-tool)
5. Open a Pull Request

---

License

MIT — Steven Bouldin