Skip to main content
Glama
deenesjakoruzh
nezolder

Civil 3D MCP Server

by nezolder
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

Civil 3D MCP Server — Dynamic Roslyn Fork

An MCP server that enables AI assistants to write and execute C# code directly inside Autodesk Civil 3D. Instead of a large set of fixed tools, the AI generates task-specific code that runs with Civil 3D API access.

Project Scope and Lineage

This fork keeps the dynamic Roslyn/C# execution model and a deliberately small public surface of three MCP tools. Its current compatibility baseline is Autodesk Civil 3D 2025, with local work focused on reliability, safety, measurable efficiency, and reusable Civil 3D skills. Other Civil 3D versions can be added later through separately verified compatibility work.

The project is derived from barbosaihan/civil3d-mcp. SantosSjba/mcp-to-c3d was evaluated for selected, test-backed ideas, while Sacred-G/Civil3D-mcp was used only as an architectural reference. See PROVENANCE.md for the detailed attribution and licensing boundaries.

This independent project is not affiliated with or endorsed by Autodesk. Autodesk assemblies and other proprietary Civil 3D files are not included.

Related MCP server: revit-mcp

Architecture

┌─────────────────┐     stdio      ┌──────────────────┐     TCP/JSON-RPC    ┌──────────────────┐
│   AI Assistant   │ ◄────────────► │  MCP Server (TS) │ ◄──────────────────► │  Civil 3D Plugin │
│ (Codex, clients) │               │   3 meta-tools    │  discovered locally │  Roslyn Engine   │
└─────────────────┘               └──────────────────┘                      └──────────────────┘
                                         │                                         │
                                    Skills Library                           C# Code Execution
                                   (.skill.md files)                      (full Civil 3D API)

3 Meta-Tools

Tool

Purpose

Safety

civil3d_execute

Execute C# code with write access; optional save after commit

⚠️ Modifies drawing

civil3d_query

Run intended read-only C# without committing the host transaction

Trusted code only; not a side-effect sandbox

civil3d_skills

Browse/search/read code skill templates; api_lookup searches already-loaded public Civil 3D API metadata

✅ Metadata only

How It Works

  1. AI reads a skill → Gets a documented C# code template

  2. AI adapts the code → Fills in parameters, combines patterns

  3. AI sends code → Via civil3d_execute or civil3d_query

  4. Roslyn compiles + runs → Inside Civil 3D with full API access

  5. Results return as JSON → Back to the AI

Example Interaction

User: "What surfaces are in my drawing?"

AI: Uses civil3d_query with:
  var surfaces = new List<object>();
  foreach (ObjectId id in CivilDoc.GetSurfaceIds()) {
    var s = Transaction.GetObject(id, OpenMode.ForRead) as TinSurface;
    surfaces.Add(new { s.Name, s.Layer });
  }
  return surfaces;

Result: [{ "Name": "EG", "Layer": "C-TOPO-EG" }, ...]

Skills Library

civil3d_skills also supports action: "api_lookup" for a bounded, read-only search of public type and member names/signatures from already-loaded allowlisted Civil 3D host assemblies. It does not load assemblies, run C# code, or access the active drawing. Supply a query and optionally an assembly, namespace prefix, and result limit.

Skills are documented C# code templates in skills/:

The current accepted catalog contains 22 skills. It includes bounded road-model inventories, template-style readiness, controlled alignment creation from an identified polyline, connected curve/spiral auditing, and a narrowly guarded fixed-primitive replacement recipe. Dynamic surface-profile/view authoring is still under development and is not included in this published catalog. See PROJECT_STATUS.md for the tested scope and remaining limitations.

skills/
├── surfaces/           # Surface operations
├── alignments/         # Alignment + station/offset
├── profiles/           # Profile inventory + elevation lookup
├── corridors/          # Corridor and baseline summaries
├── sections/           # Sample-line and section inventory
├── pipe_networks/      # Gravity pipe-network QC
├── points/             # COGO points
├── geometry/           # Lines, polylines, text
├── drawing/            # Drawing info
└── workflows/          # Complex multi-object operations

Script Globals

Code executed via civil3d_execute or civil3d_query has access to:

Global

Type

Description

Document

Document

Active AutoCAD document

CivilDoc

CivilDocument

Active Civil 3D document

Database

Database

Document database

Transaction

Transaction

Active transaction

Editor

Editor

Document editor

All Civil 3D namespaces are auto-imported.

Committing the civil3d_execute transaction changes the open drawing but does not by itself write the DWG file to disk. Set saveDrawing: true when the completed change should also be saved. The plugin saves only after the script transaction and document lock are closed; scripts must not call Database.SaveAs or queue QSAVE themselves. The save request uses a separate 10-minute default timeout and is never retried automatically.

Setup

1. Build MCP Server

npm install && npm run build

2. Build Plugin

# Copy DLLs from Civil 3D to C_References/ (see C_References/README.md)
cd plugin/Civil3dMcpPlugin
dotnet build

3. Load in Civil 3D

NETLOAD → select Civil3dMcpPlugin.dll
C3DMCPSTATUS → verify running

4. Configure AI

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

Environment Variables

Variable

Default

Description

CIVIL3D_HOST

localhost

Plugin host

CIVIL3D_PORT

unset

Optional fixed-port override. When omitted, local instance discovery is active and the plugin prefers port 8080.

CIVIL3D_CONNECT_TIMEOUT

5000

TCP connection timeout (ms)

CIVIL3D_DISCOVERY_TIMEOUT

5000

Timeout for private health and drawing-identity probes (ms)

CIVIL3D_COMMAND_TIMEOUT

120000

Execution timeout (ms)

CIVIL3D_SAVE_TIMEOUT

600000

Timeout for execute requests with saveDrawing: true (ms)

LOG_LEVEL

info

Log level

Multiple Civil 3D instances

Each loaded plugin session publishes a small local endpoint record containing only an opaque instance ID, process ID, port, and start time. It contains no drawing name or project data. The first Civil 3D instance prefers port 8080; another instance automatically uses a free localhost port.

If exactly one instance is available, existing calls work as before. With multiple instances, expectedDrawing is used to find the matching active drawing before the requested C# reaches any plugin. An unguarded bootstrap query fails closed with CIVIL3D.INSTANCE_SELECTION_REQUIRED and reports the live candidates; retry it with the optional instanceId on the existing tool. The final plugin-side drawing guard still checks the path and fingerprint immediately before Civil API access. No fourth public MCP tool is added.

Leave CIVIL3D_PORT unset for automatic selection. Setting it deliberately pins the MCP server to that one port for compatibility or diagnostics.

Benchmarking

The phase 2A host-independent recorder, the phase 2A.1 opt-in internal live trace contract, and the phase 2A.2 read-only live runner are documented in benchmark/README.md. None adds an MCP tool, queue, or retry; the 2A.2 runner can invoke only its fixed read-only query when explicitly started.

Structured errors (phase 2B.1)

civil3d_query and civil3d_execute keep their existing text error content and isError: true, while also returning structuredContent with schema civil3d-mcp-error/v1. The stable error fields are code, category, message, source, outcome, and retryable. A command timeout or a connection loss after sending has outcome: "unknown" and retryable: false; the server never retries it automatically. Successful responses and the three-tool public surface are unchanged.

An operation whose Civil command-context callback has not started within 15 seconds instead returns CIVIL3D.COMMAND_CONTEXT_TIMEOUT with outcome: "not_started" and retryable: false. A subsequently arriving abandoned callback performs no drawing work. This deadline limits admission, not execution: a started operation retains the serialized gate until native completion, and an uncertain write must still be reconciled rather than repeated. A completion recheck also closes a reproduced lost-notification window in Civil 3D 2025's native awaitable. Private health exposes fixed execution-stage names and elapsed times without drawing content; these scoped corrections do not prove that every intermittent hang is eliminated.

Private TCP framing (phase 2C.1)

Each localhost TCP connection carries one UTF-8 JSON-RPC request and one response. Each JSON body is followed by LF and is limited to 8 MiB, measured as UTF-8 bytes without the LF. The Node client still accepts the previous plugin's unframed response when that complete JSON body is followed by an orderly connection close. Oversized requests are rejected before they are written; oversized or malformed responses and interrupted connections produce non-retryable structured transport errors. If execution completed but the plugin could not return an oversized result, the reported outcome is unknown.

Operation audit logging and write idempotency (phase 2I.1 / 2I.2)

At the default info log level, each accepted civil3d_query and civil3d_execute operation emits one bounded stderr audit event. It contains a new opaque operation ID, tool name, SHA-256 and UTF-8 byte length of the C# source, success/error status, and elapsed milliseconds; errors add only stable code/category/source/outcome fields. The audit event never contains caller code, description, drawing identity, result, or error message.

civil3d_execute also accepts an optional opaque idempotencyKey (1–128 ASCII letters, digits, ., _, :, -). In one plugin session it binds the key to the UTF-8 C# SHA-256, normalized expectedDrawing identity, and saveDrawing choice. A duplicate is rejected as in-progress, conflicting, or already committed; committed entries retain no result and callers must reconcile with a read-only query. A save failure occurs after the in-memory write commit, so its key is kept as completed to prevent an accidental duplicate modification. The session keeps at most 256 completed keys, evicting the oldest deterministically. This adds neither persistence nor automatic retry or exactly-once semantics.

Security

The Roslyn sandbox blocks:

  • Process execution (Process.Start)

  • File deletion (File.Delete)

  • Network requests (HttpClient, Sockets)

  • Registry access

  • Dynamic assembly loading

All Civil 3D API operations are allowed.

This regex sandbox is defense in depth, not a trust boundary. Both code tools receive mutable Civil 3D and AutoCAD API objects; civil3d_query skips the host's transaction commit but cannot guarantee that arbitrary dynamic C# is side-effect-free. Run only trusted, approval-gated code. Loopback TCP prevents remote network access but does not authenticate other local processes.

License

MIT

Available Tools

3 tools
civil3d_executeA

Execute C# code in Civil 3D with write access. The code runs inside a committed transaction. Available globals: Document, CivilDoc, Database, Transaction, Editor. All Civil 3D namespaces are auto-imported. Return a value to get results back as JSON. Use this for operations that MODIFY the drawing (create, edit, delete objects). expectedDrawing must come from a prior read-only identity query. To persist the drawing file, set saveDrawing=true; do not call Database.SaveAs or queue QSAVE from the C# code.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesC# code to execute. Has access to Document, CivilDoc, Database, Transaction, Editor. Example: var id = TinSurface.Create(Database, "MySurface"); return new { success = true };
descriptionNoOptional human-readable summary; excluded from operation audit logs.
saveDrawingNoWhen true, save the currently named DWG after the write transaction commits and wait for completion. Use this instead of Database.SaveAs or Document.SendStringToExecute("QSAVE") in code. An unsaved drawing must first be named in Civil 3D.
idempotencyKeyNoOptional opaque session key. Reuse it only to manually reconcile an uncertain outcome; use a new key for an intentional new write.
expectedDrawingYesExpected active drawing identity checked immediately before Civil API access.

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does well: it notes the committed transaction, available globals, JSON return, drawing identity check, and save workflow. It does not mention exception handling or failure rollback, but that is a minor gap for a code-execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the core purpose, then elaborates on key parameters and constraints. It is not overly verbose, though bullet formatting could improve scannability; still, every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex code-execution tool with no output schema, the description explains available globals, return format, drawing identity requirements, save behavior, and sibling distinction. No critical operational detail is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, yet the description adds significant context: expectedDrawing provenance and check timing, saveDrawing conditions (must be named), idempotencyKey purpose, and an example for code. It clearly enhances schema-only information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a precise purpose: executing C# code with write access in Civil 3D. It explicitly scopes the tool to modifying the drawing ('Use this for operations that MODIFY the drawing'), which distinguishes it from the read-only sibling civil3d_query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear usage criteria: use for modifications, not for reads; requires expectedDrawing from a prior civil3d_query; and warns against calling Database.SaveAs or queuing QSAVE, directing the user to the saveDrawing parameter instead. This fully covers when and how to use it versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

civil3d_queryA

Execute C# code in Civil 3D in READ-ONLY mode (no changes saved). Available globals: Document, CivilDoc, Database, Transaction, Editor. All Civil 3D namespaces are auto-imported. Return a value to get results as JSON. Use this for querying data: listing objects, getting properties, analyzing surfaces, etc. Omit expectedDrawing only to bootstrap Database.Filename and Database.FingerprintGuid; otherwise supply it to guard the active drawing.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesC# code to query data. Has access to Document, CivilDoc, Database, Transaction, Editor. Example: var surfaces = new List<object>(); foreach (ObjectId id in CivilDoc.GetSurfaceIds()) { var s = Transaction.GetObject(id, OpenMode.ForRead) as TinSurface; surfaces.Add(new { s.Name, s.Layer }); } return surfaces;
expectedDrawingNoExpected active drawing identity checked immediately before Civil API access.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does substantial work: it discloses read-only semantics ('no changes saved'), available globals (Document, CivilDoc, Database, Transaction, Editor), auto-imported namespaces, the JSON return mechanism, and the expectedDrawing guard vs. bootstrap behavior. It does not cover error behavior for failed compilation or thrown exceptions at runtime, which is a notable gap for a code-execution tool, but the disclosed traits are rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: purpose/globals/return semantics, when-to-use, and the expectedDrawing rule. The first sentence is dense but not wasteful; the most critical differentiator (READ-ONLY) is front-loaded before supporting details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex code-execution tool with no annotations and no output schema, the description covers the essentials: execution mode, environment globals, namespaces, return format, and the identity-guard parameter semantics. The main omissions are error/exception behavior and the exact failure mode when expectedDrawing mismatches, which an agent invoking arbitrary C# code would benefit from knowing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds genuine value beyond the schema by explaining when to omit expectedDrawing entirely — 'Omit expectedDrawing only to bootstrap Database.Filename and Database.FingerprintGuid; otherwise supply it to guard the active drawing' — a semantic the schema's field descriptions do not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Execute C# code in Civil 3D in READ-ONLY mode (no changes saved).' It further scopes the tool with 'Use this for querying data: listing objects, getting properties, analyzing surfaces, etc.', which clearly differentiates it from the sibling civil3d_execute. An agent can tell immediately what this tool does and how it differs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this for querying data' is an explicit when-to-use statement with concrete examples. The READ-ONLY framing implies that mutations belong to the sibling civil3d_execute, though it never names that alternative or states a when-not-to-use condition explicitly, so it stops short of a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

civil3d_skillsA

Browse and read Civil 3D code skills (documented C# code templates). Use 'list' to see available skills, 'search' to find by keyword, 'get' to read the full skill with code template, or 'api_lookup' to search public metadata from already-loaded Civil 3D host assemblies. Skills are pre-built C# patterns you can adapt and execute via civil3d_execute or civil3d_query.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum list/search/api_lookup results to return (integer 1-50; default 20)
queryNoSearch query for 'search' or 'api_lookup' action
actionYeslist = browse skill metadata, search = find by keyword, get = read full skill, api_lookup = read-only public API metadata search
cursorNoOpaque nextCursor from a prior list/search call with the same filters
assemblyNoAllowlisted loaded host assembly filter for api_lookup
categoryNoFilter by category (surfaces, alignments, points, etc.)
namespaceNoNamespace prefix filter for api_lookup
skillNameNoSkill name for 'get' action

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral disclosure burden. It clearly labels the tool as read-only ('Browse and read', 'read-only public API metadata search'), implying no state changes. It also notes that execution happens via sibling tools, which further clarifies that this tool itself does not modify anything. The absence of side-effect warnings is acceptable given the read-only framing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences, each adding critical information: the core purpose, the list of actions, and the relationship to sibling tools. It front-loads the main purpose and avoids redundancy or filler. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with four actions, the description is nearly complete. It explains the actions, implies the output (list of skills, search results, full skill content, API metadata), and points to the execution siblings. While it doesn't detail pagination or output structure, those are typically understood and the schema covers cursor details. The description is sufficient for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all eight parameters have descriptions in the schema. The tool description adds contextual meaning (e.g., what 'get' does, that api_lookup is read-only) but does not explain parameter syntax or constraints beyond the schema. This meets the baseline of 3 but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair ('Browse and read Civil 3D code skills') and immediately enumerates the four supported actions (list, search, get, api_lookup). It also distinguishes itself from the sibling tools by noting that skills 'can be adapted and execute via civil3d_execute or civil3d_query.' This clearly sets its scope apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the tool's role as a browsing/reading layer and explicitly points to the sibling tools for execution. It also differentiates between read actions (list/search/get) and the read-only metadata api_lookup. While it doesn't list explicit 'when not to use' scenarios, the purpose is clear enough for an agent to decide between this and its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedcivil3d_execute
    • First observedcivil3d_query
    • First observedcivil3d_skills
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clear, non-overlapping purpose: execute for write operations, query for read-only operations, and skills for browsing code templates. The read/write distinction is explicitly stated, so agents should not confuse execute and query.

Naming Consistency4/5

All tools share the civil3d_ prefix and snake_case, but the suffixes mix verbs (execute, query) with a noun (skills), making it not a strictly consistent verb_noun pattern. The naming is still predictable and readable.

Tool Count5/5

Three tools is a well-scoped set for a server that provides arbitrary C# execution capabilities; each tool serves a distinct and necessary function. The count falls within the typical 3-15 range.

Completeness5/5

The combination of execute and query covers the full range of Civil 3D operations (create, edit, delete, query), and skills fills the learning gap. No obvious missing functionality for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers