civil3d-mcp

English · Tiếng Việt

An MCP server that drives Autodesk Civil 3D over COM. It lets Claude — or any MCP client such as Claude Code, Claude Desktop, Cursor or Cline — build TIN surface → alignment → profile → corridor → cross sections → deviation statistics from filtered point-cloud data, and export the numbers straight to CSV.

It was written for as-built BIM research on transport infrastructure, where the deliverable is a table of deviations with a defensible provenance, not a picture.

filtered point cloud            civil3d-mcp                         report
────────────────────            ───────────                         ──────
LAS/LAZ ──filter──> XYZ  ──> TIN surface ──┬─> volume surface ──> cut/fill quantities
                                           ├─> alignment ─> profile ─> station/elevation CSV
                                           ├─> corridor ─> sample lines ─> cross-section CSV
                                           └─> check points ──> RMSE, standard deviation

The point-cloud filtering step is out of scope here. A separate MCP server covers it: recap-mcp reads Autodesk ReCap projects and analyses LAS/LAZ. The two repositories are independent — either is useful on its own.

Every tool returns JSON with an ok key — {"ok": true, ...} on success, {"ok": false, "error": "..."} on failure. No tool lets an exception escape, so the model receives a readable message instead of a raw COM stack trace.

Note on documentation language. Code comments and the detailed guide are written in Vietnamese. This README is the English entry point; the Vietnamese one is README.vi.md.

What it looks like

A TIN surface built entirely through MCP calls

No project file was opened: a new drawing from the Civil 3D template, then create_tin_surface and add_points_to_surface to load the points, and create_alignment, create_profile_from_surface and create_profile_view for the rest. The full call sequence is in docs/images/README.md.

Verified on a machine with Civil 3D closed

install.py --check loads the server, counts its tools and reports which Civil 3D it found; ruff is clean; the offline suite passes — with no Civil 3D session open.

Related MCP server: Civil3D MCP Server

Requirements

• Windows. Civil 3D's COM API is Windows-only.

• Python 3.10 or newer, with pywin32 and mcp.

• Autodesk Civil 3D. Civil 3D runs on top of AutoCAD, but plain AutoCAD is not a substitute: the Surfaces/Alignments/Corridors collections only exist in Civil 3D. check_civil3d_connection detects that case and says so explicitly.

The offline test suite runs on a machine without Civil 3D installed.

Verified environment

The COM version number does not track the release year. The server discovers it from the registry rather than hardcoding it, so it keeps working when you upgrade — but the API signatures were measured against 13.8, so another version needs re-testing.

Install

git clone https://github.com/xuantinhnbs-rgb/civil3d-mcp.git
cd civil3d-mcp

pip install -r requirements.txt
python install.py

install.py detects the Python interpreter and repository directory on the machine it is running on, verifies the packages, loads the server to confirm its tools register, reports which Civil 3D installation and COM version it found, and only then writes .mcp.json. You never edit a path by hand.

python install.py --check            # verify only, write nothing
python install.py --claude-desktop   # also write Claude Desktop's config

Then open Claude Code in the repository root and run /mcp to confirm the server connected.

.mcp.json is deliberately not in the repository: it contains absolute paths valid on exactly one machine. See .mcp.json.example.

Civil 3D does not need to be running at install time — the server attaches to a session lazily.

Architecture

Civil 3D runs on top of AutoCAD: the process is still acad.exe, and the automation API comes in two layers stacked on each other.

Three design decisions worth knowing

One single COM thread. The MCP server runs tools in a thread pool, and COM does not allow interface pointers across threads. Every call — including the connection check and plain document property reads — goes through Civil3DClient.run(). Missing one entry point produces no error at that line; it makes a failure appear later, somewhere unrelated.

Writes verify themselves. A COM call that does not raise is not evidence the operation took effect. Every writing tool reads the result back and returns verified and verified_by. add_points_to_surface, for example, reports points_added_measured computed from the before/after difference in Statistics.NumberOfPoints — not the number of points it sent.

The first batch is a calibration. AddPointMultiple takes a SAFEARRAY whose layout the documentation does not pin down, and the wrong layout silently adds nothing. So the first batch goes out in the flat layout and is then measured; if the count did not rise, the server switches to array-of-arrays. The array_layout_used key in the result says which one worked.

Tools (58)

Connection and drawings

Surfaces

Alignments and profiles

Corridors and cross sections

Exporting data

A note on create_new_drawing

template_path takes a full path, not a filename:

C:\Users\<you>\AppData\Local\Autodesk\C3D 2026\enu\Template\_Autodesk Civil 3D (Metric) NCS.dwt

Pass a bare filename and Civil 3D quietly falls back to its default template. That drawing has exactly one surface style, Standard, which displays nothing — so the symptom is a surface that builds successfully, reports the right statistics, and is invisible on screen. No error is raised anywhere.

The template key in the result echoes the path that was used, so null there means no template was applied — check it rather than assuming.

Style names must also exist in the drawing. A style that is not there makes AddTinSurface fail with E_INVALIDARG, the same code as a missing BaseLayer, so the error message does not point at the real cause. The Metric NCS template ships 14 surface styles; Contours and Triangles is the clearest for a figure.

Known limits

These are properties of Civil 3D's COM API, not gaps this server could patch:

1. Assemblies and subassemblies cannot be created from scratch. AeccAssemblies exposes only Count and Item — checked against the type library, not guessed. But they can be copied: import_assembly inserts a drawing containing an assembly and the assembly comes with it. Civil 3D ships 16 sample assembly drawings in C:\ProgramData\Autodesk\C3D 2026\enu\Assemblies\Metric\ (see list_assembly_library), so in practice this is no longer a blocker.

2. Corridor targets cannot be assigned. AeccBaselineRegion has no target members, so any subassembly needing a target surface (all daylight / side-slope types) makes Rebuild fail with 0x80004005. Two ways forward: pick an assembly without daylight subassemblies, or delete that subassembly after import (subassembly.Delete() does work over COM).

3. Corridor surfaces cannot be created. AeccCorridorSurfaces is read-only too. Use corridor_points / corridor_shape_areas instead: they read the computed corridor geometry directly, which is enough for a station/offset/elevation table and for per-layer quantities.

4. Subassembly parameters cannot be edited. ParamsDouble/ParamsLong/… return a COM object on which neither Count nor Item resolves, and CastTo with a makepy'd type library still reports "Element not found". Lane width, cross slope and the like must be changed in Civil 3D's properties panel.

5. send_civil3d_command is one-way. COM returns when the command is queued; no error code comes back, and any command that waits for a mouse click will hang the UI. Verify with a reading tool after every command.

6. The drawing must come from a Civil 3D template. Creating a surface, alignment or profile requires a style that exists; a blank AutoCAD drawing has none, and the tool reports that clearly.

7. LandXML cannot be exported over COM (import only). Export goes through send_civil3d_command with -LandXMLOut, verified by checking the file on disk.

8. Large corridors take a long time to rebuild and COM blocks until finished. Read the out_of_date key: still true means the computation has not finished.

9. Units follow the drawing. The server does not convert. get_drawing_info returns measurement and drawing_units so you can check before reading numbers.

10. Volume signs follow Civil 3D's convention: cut is where the comparison surface is below the base surface. create_volume_surface states the convention in its result.

Where COM differs from its documentation

The 16 differences listed in README.vi.md were measured on Civil 3D 2026 (COM 13.8), not inferred: each is a call that was refused, or returned nothing, until it was made the way the right-hand column describes. They are all handled in this server; they are listed so that nobody reading the code thinks those lines are redundant, and so the next person writing a Civil 3D tool loses less time.

A few highlights:

• Surfaces.AddTinSurface demands both Layer and BaseLayer; omitting BaseLayer surfaces as a generic "Exception occurred".

• Profiles.AddFromSurface wants the surface name as a string, while SampleLineGroups.Add wants a style object — the opposite convention, in the same API.

• Surfaces.Item(i) hands back the base IAeccSurface interface, with no Statistics. The object returned by AddTinSurface at creation time carries the derived interface, so the same line of code works right after creating a surface and fails when the drawing is reopened in a later session.

• AeccRoadwayDocument.Assemblies refuses the property itself with E_INVALIDARG when the drawing has no assemblies, so "none yet" looks exactly like "the call is broken".

The full table, with all 16 rows and three further behavioural notes, is in the Vietnamese README. A test asserts that the count stated in prose matches the number of rows in the table — that sentence had already drifted once.

Development

pip install -r requirements-dev.txt

ruff check .                 # lint
pytest                       # offline suite; no Civil 3D needed
python install.py --check    # loads the server, prints tool count and Civil 3D version

# Live suite: builds real geometry in a running Civil 3D
$env:CIVIL3D_LIVE_TEST=1; pytest tests/test_live_civil3d.py

The first three are exactly what CI runs.

The offline suite runs on a machine without Civil 3D — which is why CI can run it at all. It uses a fake COM layer to exercise the paths a real machine rarely reaches:

• a COM call that "succeeds" without taking effect (creating a surface that does not appear, loading points that do not arrive);

• a wrong array layout being silently ignored, and the calibration step catching it;

• regressions for differences #1, #2 and #6 in the table — removing the BaseLayer assignment or dropping coordinates to 2D turns those tests red;

• two non-overlapping surfaces (the signature of mismatched coordinate systems) producing an error that names the cause;

• "busy" being distinguishable from "not running";

• deviation statistics: RMSE about zero differs from standard deviation about the mean when there is a bias.

The computation in geometry.py is tested against hand-computable values (a 3-4-5 triangle, the RMSE of a symmetric series, the area of a square), never against reference values copied from a previous run.

The live suite (CIVIL3D_LIVE_TEST=1) builds two parallel planes exactly 0.05 m apart over 100 × 40 m, then requires Civil 3D to return the analytic answer:

"It ran without an error" is not the criterion: every step has to produce the right number. This suite is what found all 16 API differences above.

See CONTRIBUTING.md for conventions and the checklist for adding a tool, and CHANGELOG.md for what changed between versions.

Troubleshooting

Security

This server hands a model direct control of the open drawing: it can delete surfaces, save over files, and send arbitrary AutoCAD commands. Read SECURITY.md before connecting it, and report vulnerabilities privately rather than in a public issue.

License

MIT — free for any use including commercial, keep the copyright notice.

Contributions are welcome in English or Vietnamese — see CONTRIBUTING.md and CODE_OF_CONDUCT.md.