Skip to main content
Glama
civil-qto-mcp

civil-qto-mcp

civil-qto-mcp

CI License: MIT Python 3.11+ MCP Tests

Deterministic Model Context Protocol (MCP) Server for Civil Engineering, Roadworks, Paving, Earthworks, Foundations & Utilities Quantity Take-Off (.dxf / .dwg / .pdf) and Bill of Quantities (.xlsx / .xlsm) Auditing.


Why civil-qto-mcp?

Vision LLMs and naive text-dump scripts fail on real-world civil engineering drawings and construction budgets:

  • Real CAD drawings are messy: Inconsistent layer names, exploded LINE/ARC segments, overlapping duplicate lines (OVERKILL not run), unclosed polygons with $2\text{–}8\text{ cm}$ gaps, 3D "Flying Z" elevation snaps on 2D plans, mirrored OCS entities (extrusion Z = -1), and mismatched $INSUNITS headers on national grid coordinates (such as UTM / ETRS89, Gauss-Krüger, UK OSGB36, US State Plane, or Hungarian EOV / HD72 EPSG:23700).

  • Real Excel BoQs contain traps: Hidden internal calculation worksheets, hidden alternative rows, split Material + Labor + Equipment columns (TERC / ÉNGY, DIN VOB/C, or CESMM4 layouts), hardcoded numbers overwriting live formulas, and incomplete =SUM(...) ranges.

civil-qto-mcp bridges AI agents (Claude Code, Claude Desktop, Cursor, Antigravity) with exact C++ computational geometry (Shapely 2.0 / GEOS + ezdxf) and exact Decimal spreadsheet auditing (openpyxl), governed by a 3-Step Human-in-the-Loop (HITL) engineering workflow:

flowchart TD
    subgraph Step1["1. Discovery & CAD Conversion"]
        T6["convert_dwg_to_dxf"] --> T1["inspect_civil_dxf"]
        T9["convert_vector_pdf_to_dxf"] --> T1
    end
    subgraph Step2["2. Deterministic 2D/3D CAD Take-Off"]
        T1 --> T2["measure_linear_and_area_features"]
        T1 --> T3["extract_utility_network_and_levels"]
        T1 --> T10["extract_longitudinal_profile_data"]
        T1 --> T14["calculate_foundation_and_slab_qto"]
        T1 --> T16["calculate_tin_earthwork_volumes"]
        T2 --> T8["calculate_pavement_layer_quantities"]
        T3 --> T7["optimize_precast_manhole_elements"]
        T2 --> T12["export_qto_visual_overlay"]
    end
    subgraph Step3["3. BoQ Auditing, Completeness, Pricing & Revisions"]
        T4["inspect_and_audit_boq_xlsx"] --> T5["compare_qto_with_boq"]
        T4 --> T13["audit_technological_completeness"]
        T4 --> T15["match_prices_and_generate_rfq"]
        T13 --> T11["apply_boq_modifications_and_pricing"]
        T15 --> T11
        T17["compare_drawing_and_boq_revisions"] --> T11
    end

Related MCP server: ai-cad-workbench

Complete Tool Reference (v0.5.0 – 17 Deterministic Tools)

#

Tool Name

Category

Purpose & Engineering Guarantees

1

inspect_civil_dxf

CAD Discovery

Lists Modelspace layers (ignoring Paperspace layouts) from .dxf or .dwg files, extracts INSERT block names, ATTRIB tag names, and cleaned TEXT/MTEXT samples. Performs 3-factor CRS & unit scale estimation and flags CAD hygiene issues.

2

measure_linear_and_area_features

2D QTO

Measures linear features ($\text{m}$) with analytical circular arc (bulge) calculation, 2D horizontal projection ($Z \equiv 0$), and 1D Shapely overlap deduplication. Measures net surface areas ($\text{m}^2$) via 2D boolean .difference() (preventing double-deduction on perforated HATCHes) with configurable VOB/C (DIN 18318) minimum island deduction thresholds (min_island_deduction_m2).

3

extract_utility_network_and_levels

Utilities

Extracts manholes/gullies (INSERT, CIRCLE, box LWPOLYLINE) and utility pipes. Matches Cover (CL/OK/F) and Invert (IL/S/Ff) levels across EN/DE/HU profiles in priority order: (1) insert.attribs (ATTRIB), (2) LEADER arrow tip tracing, (3) STRtree spatial proximity. Calculates DIN 4124 / EN 1610 trench excavation, bedding/pipe-zone, pipe displacement, and backfill volumes ($\text{m}^3$).

4

inspect_and_audit_boq_xlsx

BoQ Audit

Safely parses .xlsx and .xlsm BoQs while strictly excluding hidden / veryHidden worksheets and hidden rows. Supports 1-column, 2-column (Material+Labor), and 3-column (Labor+Material+Equipment) layouts, keyword_filter + limit/offset pagination, and audits 100% of visible rows for MATH_MISMATCH, HARDCODED_TOTAL, SUM_RANGE_GAP, SHARED_FORMULA_RISK, and ZERO_UNIT_PRICE.

5

compare_qto_with_boq

Cross-Check

Deterministically cross-checks CAD QTO quantities against Excel BoQ items with built-in international construction unit synonym & scale conversion (m $\leftrightarrow$ fm/lm/lfm/km/ft/yd, m2 $\leftrightarrow$ nm/sqm/ha/sqft, m3 $\leftrightarrow$ lm3/bm3/cum/cy, pcs $\leftrightarrow$ ea/nr/st/stk/db/akna/ls).

6

convert_dwg_to_dxf

CAD Loader

Batch-converts .dwg files (or directories of .dwg files) to .dxf with SHA-256 content caching and binary AutoCAD header detection (AC1015..AC1032) via AutoCAD Core Console (accoreconsole), ODA File Converter, or LibreDWG.

7

optimize_precast_manhole_elements

Utilities

Decomposes manholes (DN1000/DN1200/48") and $50\times 50\text{ cm}$ road gullies into optimal precast concrete modules across DIN EN 1917, ASTM C478, and SzeBeton T2 catalogs (AFE base, ASZ cone or shallow AFT flat cover slab, AGY 100/75/50/25 cm shaft rings, SZB 10/8/6 cm adjustment rings, and D400 covers) and builds a consolidated manufacturer RFQ Bill of Materials (BOM).

8

calculate_pavement_layer_quantities

Roadworks

Calculates multi-layer road and paving structural quantities ($\text{m}^2$, compacted $\text{m}^3$, order $\text{m}^3$, and metric tons $\text{t}$) accounting for lateral step-out widening beyond curb lines, compaction multipliers (e.g., CBM / CKT-4 $\times 1.20$), and cutting/overlap waste (EN 13108 / EN 13285 / EN 14227).

9

convert_vector_pdf_to_dxf

PDF Import

Imports vector PDF engineering drawings into layered DXF files via AutoCAD Core Console (_-PDFIMPORT) and automatically calibrates recommended_scale_factor_to_meters from reference dimensions, explicit scale ratios, or title-block scale texts (M=1:250, Scale 1:500).

10

extract_longitudinal_profile_data

Utilities

Parses utility longitudinal profile (EN / DE / HU station bands: Ground Level/Geländehöhe/Terepszint, Invert/Sohlhöhe/Csőfenék, Station/Stationierung/Szelvény) to calculate trench excavation, machine vs. hand excavation split at utility crossings, two-sided shoring area ($\ge 1.25\text{ m}$), and shallow-cover ($<1.00\text{ m}$) C12/15 concrete encasement volumes ($\text{m}^3$).

11

apply_boq_modifications_and_pricing

BoQ Writer

Safely writes unit prices (with optional markup_factor and currency-safe round_step), red-bold quantity modifications, supplemental items (SUPPLEMENTAL_ITEM / K_TETEL), and -/+ variation order pairs (VARIATION_PAIR / KIV_ESZREVETEL_PAIR) into Excel BoQ workbooks while updating SUM ranges, populating XML <v> cached values, and stripping xl/calcChain.xml.

12

export_qto_visual_overlay

Visual QA

Exports an interactive standalone .html and .svg visual verification map (locale="en" | "de" | "hu") highlighting all measured net surface polygons, deducted islands, linear features, and point nodes with their exact $\text{m}^2$ / $\text{m}$ quantities.

13

audit_technological_completeness

Completeness

Scans BoQ workbooks against 6 civil engineering technological completeness chains (asphalt, block paving, gravity sewers, pressure water lines, RC foundations, industrial slabs) to detect omitted companion items (missing curbs, tack coat, tie-in saw-cutting, manhole cover count mismatches, shallow pipe concrete encasement, slab joints) and outputs ready-to-insert supplemental items.

14

calculate_foundation_and_slab_qto

Structures

Calculates the complete structural and earthwork quantity chain for pad footings, cup footings, strip foundations, plinth walls, raft slabs, and industrial floors: structural concrete ($\text{m}^3$), blinding concrete with $+10\text{ cm}$ lateral overhang ($\text{m}^3$), lateral formwork ($\text{m}^2$), rebar/fiber tonnage ($\text{t}$), DIN 4124 prismoidal pit excavation ($\text{m}^3$), plinth XPS insulation ($\text{m}^2$), and saw-cut contraction joints ($\text{m}$).

15

match_prices_and_generate_rfq

Pricing & RFQ

Matches BoQ line items against 3-tier regional unit-price databases (own historical DB, supplier price lists, and built-in benchmarks), flags transport-sensitive items, generates ready-to-apply BoQRowPricingInput payloads, and groups materials into 6 procurement RFQ packages with regional supplier contacts.

16

calculate_tin_earthwork_volumes

3D Earthworks

Computes 3D Delaunay TIN surface earthwork volumes (topsoil_strip_volume_m3, cut_volume_bank_m3, fill_volume_compacted_m3, and net_earth_balance_m3) between existing terrain and designed subgrade level (accounting for pavement structure thickness offset and zero-line nullvonal sub-triangle integration) directly from CAD spot-elevation layers or 3D point clouds without Civil 3D.

17

compare_drawing_and_boq_revisions

Revisions

Compares Old (R0 / Design) vs. New (R1 / As-Built) CAD drawings and/or BoQ Excel workbooks, reporting spatial polygon additions/removals (New - Old and Old - New), linear/point deltas, row-level BoQ diffs, and ready-to-insert variation order payloads.


Quick Start & Installation

1. Claude Code CLI (claude mcp add)

claude mcp add civil-qto -- uvx civil-qto-mcp

2. Claude Desktop / Cursor / Antigravity (mcp_config.json)

{
  "mcpServers": {
    "civil-qto": {
      "command": "uvx",
      "args": ["civil-qto-mcp"]
    }
  }
}

3. Run from Local Source Repository

{
  "mcpServers": {
    "civil-qto": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/civil-qto-mcp",
        "run",
        "civil-qto-mcp"
      ]
    }
  }
}

Development & Automated Testing

All 35 geometric, structural, earthwork, and spreadsheet edge cases are tested deterministically using programmatic synthetic DXF (tests/factories/dxf_factory.py) and XLSX (tests/factories/xlsx_factory.py) generators—requiring zero proprietary client drawings in CI.

# Install dependencies including dev tools
uv sync --extra dev

# Run Ruff linter
uv run ruff check src tests

# Run Pytest test suite (35 tests across v0.1..v0.5)
uv run pytest -v

License

Released under the MIT License. Copyright (c) 2026 András Sándor Laczi.

Available Tools

17 tools
apply_boq_modifications_and_pricingB
[v0.3 Tool 11] Safely write unit prices (with optional markup_factor), red-bold quantity modifications,
supplemental K-tételek, and '-'/'+' kiv. észrevétel pairs into an Excel BoQ workbook while updating
SUM ranges, XML `<v>` cached values, and stripping `xl/calcChain.xml`.

Inputs: output_xlsx_path (required), source_xlsx_path (required), round_step, row_pricings, +2 more. Returns: Output schema for Tool 11: apply_boq_modifications_and_pricing.

audit_technological_completenessA
[v0.4 Tool 13] Audit a BoQ workbook against 6 civil engineering technological completeness chains
(asphalt, block paving, gravity sewers, pressure water lines, RC foundations, industrial slabs)
and generate ready-to-insert `BoQSupplementalItemInput` (K-tétel) payloads for omitted items.

Inputs: boq_xlsx_path (required), locale, sheet_names, cad_curb_length_m, +2 more. Returns: Output schema for Tool 13: audit_technological_completeness.

calculate_foundation_and_slab_qtoB
[v0.4 Tool 14] Calculate the full structural and earthwork quantity chain for foundations, plinths,
and industrial floor slabs: structural concrete (m3), blinding concrete with lateral overhang (m3),
lateral formwork (m2), rebar/fiber tonnage (t), DIN 4124 prismoidal excavation (m3), plinth XPS (m2),
and saw-cut contraction joints (m).

Inputs: elements, file_path_cad, working_space_m, batter_angle_deg, +6 more. Returns: Output schema for Tool 14: calculate_foundation_and_slab_qto.

calculate_pavement_layer_quantitiesA
[v0.2 Tool 8] Calculate structural layer quantities (m2, m3, metric tons) for road and paving works,
accounting for lateral step-out widening beyond curb lines, compaction multipliers (e.g., CKT-4 x1.20),
and cutting/overlap waste.

Inputs: net_surface_area_m2 (required), preset_name, custom_layers, active_edge_perimeter_m. Returns: Output schema for Tool 8: calculate_pavement_layer_quantities.

calculate_tin_earthwork_volumesB
[v0.5 Tool 16] Compute 3D Delaunay TIN surface earthwork volumes (topsoil stripping, cut, fill,
and net earth balance) between existing terrain and designed subgrade level directly from
CAD spot-elevation layers or 3D point clouds (without Civil 3D).

Inputs: design_points, file_path_cad, boundary_layers, existing_points, +7 more. Returns: Output schema for Tool 16: calculate_tin_earthwork_volumes.

compare_drawing_and_boq_revisionsB
[v0.5 Tool 17] Compare Old vs. New (or Design vs. As-Built) CAD drawings and/or BoQ Excel workbooks,
calculating spatial area additions/removals (`New - Old` and `Old - New`), linear/point deltas,
row-level BoQ diffs, and ready-to-apply variation order (`kiv. észrevétel` / `K-tétel`) payloads.

Inputs: locale, sheet_names, new_cad_path, old_cad_path, +6 more. Returns: Output schema for Tool 17: compare_drawing_and_boq_revisions.

compare_qto_with_boqA
[STEP 3D of HITL Workflow] Deterministically cross-check CAD QTO measurements against Excel BoQ items.

Automatically normalizes construction unit synonyms and scale factors:
- Length: `m` == `fm` == `lm` == `folyóméter`, `km` == `1000 m`, `cm` == `0.01 m`, `mm` == `0.001 m`
- Area: `m2` == `m²` == `nm` == `sqm`, `ha` == `10,000 m2`
- Volume: `m3` == `m³` == `lm3` == `bm3` == `tm3` == `cum`
- Count: `pcs` == `db` == `darab` == `akna` == `klt` == `készlet` == `nr` == `ea`

Inputs: qto_records (required), file_path_xlsx (required), sheet_names, critical_percent, +1 more. Returns: Output schema for Tool 5: compare_qto_with_boq.

convert_dwg_to_dxfA
[v0.2 Tool 6] Convert a single .dwg file or an entire folder of .dwg files into .dxf format.
Note: `inspect_civil_dxf`, `measure_linear_and_area_features`, and `extract_utility_network_and_levels`
also accept `.dwg` paths directly via transparent background caching.

Inputs: source_path (required), use_cache, output_dir, target_dxf_version. Returns: Output schema for Tool 6: convert_dwg_to_dxf.

convert_vector_pdf_to_dxfA
[v0.3 Tool 9] Convert a vector PDF civil engineering plan into a layered DXF drawing via AutoCAD
Core Console (`_-PDFIMPORT`) and automatically calibrate `recommended_scale_factor_to_meters`
from reference dimensions, explicit scale denominator, or title-block scale text ('M=1:250').

Inputs: pdf_path (required), page_number, output_dxf_path, pdf_import_base_unit, +3 more. Returns: Output schema for Tool 9: convert_vector_pdf_to_dxf.

export_qto_visual_overlayB
[v0.3 Tool 12] Export an interactive HTML and SVG visual verification map showing all measured
polygons, deducted islands, linear features, and point nodes labeled with their IDs and m2/m quantities.

Inputs: file_path (required), locale, output_dir, point_layers, +4 more. Returns: Output schema for Tool 12: export_qto_visual_overlay.

extract_longitudinal_profile_dataB
[v0.3 Tool 10] Analyze a utility longitudinal profile (hossz-szelvény) to compute trench excavation,
machine vs. hand excavation split at utility crossings, two-sided shoring area, and shallow-cover
(<1.00 m) C12/15 concrete encasement volumes.

Inputs: dxf_path, stations, crossings, profile_name, +7 more. Returns: Output schema for Tool 10: extract_longitudinal_profile_data.

extract_utility_network_and_levelsB
[STEP 3B of HITL Workflow] Extract utility manholes/gullies, levels, pipe segments, and DIN 4124 / EN 1610 trench earthworks.

Priority order for manhole data extraction:
1. `INSERT` block attributes (`insert.attribs` / `ATTRIB` tags for ID, Cover/Rim level, Invert level, DN)
2. Leader-aware spatial matching (`LEADER` / pointer line arrow tips pointing to manholes)
3. `STRtree` spatial proximity matching within `search_radius_m` (supporting HU, DE, and EN callout syntax)

Inputs: file_path (required), node_layers, pipe_layers, text_layers, +9 more. Returns: Output schema for Tool 3: extract_utility_network_and_levels.

inspect_and_audit_boq_xlsxA
[STEP 3C of HITL Workflow] Safely parse and mathematically audit an Excel (.xlsx / .xlsm) Bill of Quantities.

Safety & Auditing Features:
- Strictly skips `hidden` and `veryHidden` worksheets (listing them in `skipped_hidden_sheets`)
- Strictly skips hidden rows (`row_dimensions[r].hidden`)
- Automatically detects Single-Price and Hungarian TERC Split (Material + Labor) column layouts
- Audits 100% of rows on selected visible sheets for `MATH_MISMATCH`, `HARDCODED_TOTAL`,
  `SUM_RANGE_GAP`, `SHARED_FORMULA_RISK`, `ZERO_QUANTITY`, and `ZERO_UNIT_PRICE`
  (even when `keyword_filter` or `limit` paginates the returned `items` list)

Inputs: file_path (required), limit, offset, sheet_names, +1 more. Returns: Output schema for Tool 4: inspect_and_audit_boq_xlsx.

inspect_civil_dxfA
[STEP 1 of HITL Workflow] Inspect a civil engineering DXF drawing before any measurement.

Returns:
- Modelspace vs. Paperspace entity counts and 3D bounding box
- 3-factor CRS & Drawing Unit estimation (auto-detects Hungarian EOV HD72 metric coordinates,
  checks $INSUNITS header mismatches, and analyzes median text heights)
- Per-layer entity type breakdown, closed/open/nearly-closed polyline counts, HATCH counts,
  distinct INSERT block names, block ATTRIB tag names, and cleaned sample texts
- CAD Hygiene Warnings (Civil 3D proxy objects, external XREFs, 3D 'Flying Z' elevation jumps,
  nearly-closed polylines, and duplicate segments)

After calling this tool, present the layer mapping and `recommended_unit_scale_to_meter`
to the user for confirmation before calling `measure_linear_and_area_features` or
`extract_utility_network_and_levels`.

Inputs: file_path (required), max_sample_texts, layer_filter_regex, ignore_empty_layers. Returns: Output schema for Tool 1: inspect_civil_dxf.

match_prices_and_generate_rfqB
[v0.4 Tool 15] Match BoQ items against regional unit-price databases (Tier 1 own regional DB,
Tier 2 supplier catalogs, Tier 3 built-in benchmarks), flag transport-sensitive items, produce
ready-to-apply `BoQRowPricingInput` payloads, and group materials into 6 supplier RFQ packages.

Inputs: boq_xlsx_path (required), round_step, sheet_names, database_dir, +2 more. Returns: Output schema for Tool 15: match_prices_and_generate_rfq.

measure_linear_and_area_featuresA
[STEP 3A of HITL Workflow] Deterministically measure linear lengths (m) and net surface areas (m2).

Engineering guarantees:
- Enforces 2D horizontal projection (Z=0) so 3D 'Flying Z' vertices never distort lengths
- Analytical circular arc (`bulge`) length calculation + sagitta-bounded spline/ellipse discretization
- 1D topological deduplication of exact and partially overlapping lines
- 2D Shapely boolean `.difference()` for island subtraction (guaranteed immunity against
  double-deduction even when HATCH entities already contain internal hole loops)

Inputs: file_path (required), linear_layers, boundary_layers, explode_inserts, +7 more. Returns: Output schema for Tool 2: measure_linear_and_area_features.

optimize_precast_manhole_elementsB
[v0.2 Tool 7] Decompose manholes and road gullies into optimal precast concrete elements
(base AFE, cone ASZ or shallow flat slab AFT, shaft rings AGY 100/75/50/25 cm, adjustment rings SZB 60/10, 60/8, 60/6 cm,
and D400 covers/grates) and generate a consolidated manufacturer RFQ Bill of Materials (BOM).

Inputs: manholes, node_layers, text_layers, file_path_cad, +5 more. Returns: Output schema for Tool 7: optimize_precast_manhole_elements.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools have clearly distinct scopes, especially around CAD inspection, measurement, conversion, and BoQ handling. There is some potential overlap among the multiple calculation tools and among BoQ audit/pricing tools, but the detailed descriptions and explicit workflow steps mostly resolve those boundaries.

    Naming Consistency5/5

    All tool names use snake_case and are predominantly verb-led with a clear object or action phrase. The pattern is highly predictable across the entire set.

    Tool Count4/5

    The 17 tools cover a complex civil QTO and BoQ workflow, and each appears to serve a specialized role. The count is slightly heavy but reasonable for the breadth of the domain.

    Completeness4/5

    The surface covers inspection, conversion, measurement, utility extraction, BoQ auditing, comparison, pricing, modification, and visualization. Minor gaps may exist around creating a BoQ from scratch or non-vector PDF handling, but core workflows are well covered.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Modern CAD CLI + MCP Server: 2D/3D drawing, editing, measurement, validation, batch automation, real-time collaboration (CRDT + WebSocket).
      22
      2
      Apache 2.0
    • A
      license
      C
      quality
      B
      maintenance
      Local DWG/DXF-to-GIS conversion and QGIS delivery with validation evidence. MCP and agent plugins add 15 verified source-preserving CAD tools through an optional isolated runtime; original code is Apache-2.0.
      63
      4
      Apache 2.0
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to draft, read, validate, diff, and take off CAD drawings through a single typed contract served by either a live COM session or a headless ezdxf engine. Ships 247 tools covering P&ID, mechanical, and architectural drafting, with ISO GD&T and dimension-tolerance validation plus spec-to-drawing and takeoff-to-workbook workflows.
      -