mto-mcp-server
An MCP server that reconciles piping MTO files against Plant 3D SCSA exports, offering read-only diffing and gated, previewable write-back.
Diff MTO vs SCSA: Compare an MTO .xlsx against a SCSA .xlsx export and get a summary plus itemized lists for quantity mismatches, removed items, and new items.
Filter by category: Optionally restrict the diff to a specific piping category (elbow, valve, gasket, etc.) or everything at once.
Preview changes safely: Run
apply_mto_updatewithdry_run=Trueto see exactly what would be written without modifying any file.Apply quantity corrections and additions: With
dry_run=False, update MTO quantities to match SCSA and insert new items (additive/corrective changes).Gate destructive removals: Zero out removed items only when
include_removals=Trueis explicitly set, keeping deletions a deliberate, separate step.Write to a different file: Use
output_pathto avoid overwriting the original MTO in place.Re-derive diffs on every write: The apply tool recalculates from the two paths each call, so stale or tampered diffs are never trusted.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mto-mcp-server Preview the diff between my MTO and the Plant 3D SCSA export"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mto-mcp-server

An MCP server that reconciles a piping MTO (Material Take-Off) against a Plant 3D SCSA export, for industrial EPC projects. A short .gif demo is presented above.
The problem
MTOs drift out of sync with the model as a piping design evolves. Bringing one back in line is a recurring, mechanical-but-error-prone task: diff two Excel exports with different shapes, decide what changed, update quantities, add new items, and — carefully — remove items that dropped out of the design. Doing this by hand across hundreds of rows and 8 piping categories (pipes, elbows, tees, reducers, flanges, valves, blind flanges, gaskets) is slow and easy to get subtly wrong.
Related MCP server: grid-intake
Why MCP instead of a script
The reconciliation logic itself could be a plain script. What makes this an agent tool rather than a script is the shape of the two calls:
diff_mto_scsaonly ever computes and reports. It's built so an LLM can call it, read the result, and reason about it in natural language — "SCSA shows 4 of these, MTO has 3, want me to bump it?" — before anything is written.apply_mto_updateis split into a safe path (quantity corrections, new items — additive/corrective) and a gated path (removals — zeroing a quantity because the item left the design, which is destructive). The gate is two independent flags,dry_runandinclude_removals, not a single "confirm" toggle, so an agent (or a human driving it) can preview everything withdry_run=True, apply the safe part, and only zero items out onceinclude_removals=Trueis passed explicitly and deliberately.
That two-tool shape — compute-and-explain, then gated-write — is the actual point of the project: it's the difference between "a script that mutates your MTO" and "a tool an agent can be trusted to drive."
Scope
This project demonstrates the reconciliation logic end-to-end against
real elbow (Отвод) data — the two tools, the 3 scenarios, and the
confirm-gate on removals are all built and tested against real MTO/SCSA
files. Category-specific matching for other categories (valve check-type
synonyms, reducer family+OD-pair+line) exists as draft code in
matching.py but is intentionally not wired in — see "Known limitations"
below. Everything not elbow-specific (normalization, the diff/apply split,
the write logic) is category-agnostic and applies to any category once its
match key is validated.
Built on prior work
The core normalization and categorization logic is ported, not
rewritten, from
rustam-zarifov/mto-scsa-reconciliation —
a 6-script toolkit built from real EPC piping reconciliation work, covering
all 7 major categories with a color-coded Excel report as output. That
toolkit's raw-file assumptions (a 26-column master_mto.xlsm with section
headers, feeding an intermediate MTO_Lookup_Table; a header-named SCSA
export) don't match the simpler raw exports this project was tested
against, so the I/O layer (io_excel.py) here is new. What's ported:
normalize.py'sclassify_category()— the keyword-based category rules, straight from that project'scategorize()(now covering fasteners, insulation, and structural steel too, not just the 8 piping categories, since the keyword list came over wholesale).normalize.py's Cyrillic х/Latin x unification, from that project'snorm().domain_addons.py— GOST year-format normalization, line-code recovery, OD→DN lookup, and pipe-segment splitting, ported in full from4_normalization_addons.py. Not wired into matching yet — elbows don't hit any of these cases; they're here for when gasket/pipe/flange matching gets built out.apply.py's_redistribute_group()— proportional redistribution across multiple MTO rows sharing one match key, from that project's5_apply_fixes.py, replacing an earlier "dump into one row, zero the rest" approach.
One thing that did not port: that project's match key is
(name, material), using a Материал column present on both sides of its
pipeline. This project's raw MTO export has no comparable material column
(only a line code, which turned out to be unreliable — see below), so the
match key here stays name-only until that gap is closed.
The 3 scenarios
Scenario | Condition | Action |
Qty mismatch | item in both, quantities differ (either direction) | update MTO qty to match SCSA |
Removed | item in MTO, no longer in SCSA | zero the MTO qty (gated, see above) |
New | item in SCSA, not yet in MTO | insert into MTO with SCSA's qty |
Items with matching quantities in both files produce no diff entry (counted
in summary.matched only) — this is checked directly in the test suite, not
assumed.
Install
pip install -e .Requires mcp>=1.9.0,<2.0.0. Note: pip install "mcp[cli]" on its own
pulls the 2.x line, which drags in a much heavier dependency set
(opentelemetry, jsonschema, pyjwt>=2.10) that isn't needed for a local
stdio server. This project pins <2.0.0 deliberately.
Run
mto-mcp-serveror point a Claude Desktop / Claude Code MCP config at
python -m mto_mcp_server.server.
Tools
diff_mto_scsa(mto_path, scsa_path, category=None)
Read-only. Returns:
{
"summary": {"matched": 1, "qty_mismatch": 2, "removed": 2, "new": 2},
"qty_mismatch": [{"name": "...", "line": "...", "mto_qty": 3, "scsa_qty": 4, ...}],
"removed": [{"name": "...", "mto_qty": 1, ...}],
"new": [{"name": "...", "scsa_qty": 1, ...}]
}category optionally restricts to one of the categories classify_category()
produces — the 8 piping categories (pipe, elbow, tee, reducer,
flange, valve, blind_flange, gasket) plus the extra buckets that
came along with the ported keyword rules (stud_bolt, bolt, nut,
washer, gate_valve, safety_valve, ball_valve, steam_trap,
pipe_support, insulation, structural_steel). Omit it to diff
everything.
apply_mto_update(mto_path, scsa_path, category=None, include_removals=False, dry_run=False, output_path=None)
Re-derives the diff internally from mto_path/scsa_path every call —
it does not accept a pre-computed diff object from the caller. That
keeps the tool safe against a stale or hand-edited diff being replayed,
and keeps diff_mto_scsa a true preview with no side effects to trust.
dry_run=True→ compute and report, write nothing.dry_run=False, include_removals=False(default) → applies qty fixes and inserts; removals are reported but not written.dry_run=False, include_removals=True→ also zeroes removed items.output_path→ write to a different file instead of overwritingmto_pathin place.
Matching design
Normalization: strips
°, a trailing?, collapses whitespace, and unifies Cyrillic "х" / Latin "x" (a real bug source in dimension strings like "160x5") before any comparison.Default match key is name-only, not name+line. In the real SCSA export, line-code columns are populated for some standards (GOST) and empty for others (ASME) — see
tests/fixtures/scsa_test.xlsx. Requiring line in the key would silently drop real matches. Line is still carried through on every diff entry as display metadata.Valves and reducers: the spec calls for check-type valve synonym folding (
Обратный клапан=Обратный затвор) and family+OD-pair+line matching for reducers, but there was no real valve or reducer data available to validate either against — only elbow data was available. Both key functions exist as drafts inmatching.py(valve_key,reducer_key) but are not wired in — see the_KEY_FUNCScomment. Both categories currently fall through to the name-only default key. Wiring either back in is a one-line change once there's real data to check it against.GOST/ASME cross-referencing falls out of the name-only key for free — the standard field is read but deliberately excluded from the key.
Testing
tests/test_diff.py runs against real (small) MTO/SCSA export pairs in
tests/fixtures/, not synthetic data. Expected values were derived by
hand-tracing the fixture files first, then asserted — not read off the
code's own output. Covers: exact-match (no false flag), qty mismatch in
both directions, removed items, new items, dry-run (no write), apply
without removals (removed items untouched), apply with removals (zeroed),
and new-item insertion (qty + next POZ number).
pip install pytest
pytest tests/ -vKnown limitations / next steps
Category-specific matching (valve check-type synonyms, reducer family+OD-pair+line) is drafted but not validated against real data — see above. Demo and tests currently cover elbow reconciliation only.
The match key is name-only, not
(name, material)like the ported toolkit's proven engine — this project's raw MTO export doesn't expose a comparable material field yet. See "Built on prior work" above.domain_addons.pyis ported but not wired into any matching path yet.Column positions in
io_excel.py(MTO_COLUMNS,SCSA_COLUMNS) are verified against the two fixture files only; a different SCSA export layout would need the indices adjusted.
Available Tools
2 toolsapply_mto_updateA
Write the MTO/SCSA reconciliation into the MTO file.
Always re-derives the diff from the two paths (never trust a caller-supplied diff blob). Quantity corrections and new items are applied whenever dry_run=False - they're additive/corrective, not destructive. Removals (zeroing a quantity because the item left the project) are ONLY written when include_removals=True as well.
Recommended flow: call with dry_run=True first to preview writes, then call again with dry_run=False, and include_removals=True only once you've reviewed the removed list.
Args: mto_path: path to the MTO .xlsx file to update. scsa_path: path to the SCSA .xlsx export (source of truth). category: optional category filter, same as diff_mto_scsa. include_removals: if True, zero out items no longer in SCSA. dry_run: if True, compute and report but write nothing. output_path: write to a different file instead of overwriting mto_path. Defaults to overwriting mto_path in place.
Inputs: mto_path (required), scsa_path (required), dry_run, category, +2 more.
diff_mto_scsaA
Compare an MTO file against a Plant 3D SCSA export.
Read-only - never writes anything. Returns counts and item lists for the 3 scenarios: qty_mismatch, removed (in MTO, not in SCSA anymore), new (in SCSA, not yet in MTO). Items with matching qty in both are counted in summary.matched but not listed individually.
Args: mto_path: path to the MTO .xlsx file. scsa_path: path to the SCSA .xlsx export. category: optional filter - one of pipe/elbow/tee/reducer/flange/ valve/blind_flange/gasket/stud_bolt/bolt/nut/washer/ gate_valve/safety_valve/ball_valve/steam_trap/pipe_support/ insulation/structural_steel. Omit to diff everything.
Inputs: mto_path (required), scsa_path (required), category.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct roles: diff_mto_scsa is explicitly read-only comparison, while apply_mto_update is write-back with dry-run and removal safeguards. There is no realistic ambiguity about which tool to select for a given task.
Both names follow a consistent verb_noun snake_case pattern: diff_mto_scsa and apply_mto_update. The shared 'mto' prefix ties them to the same domain, and the verbs clearly signal read vs. write actions.
Two tools is slightly below the typical 3-15 range, but this is a deliberately narrow reconciliation workflow where diff and apply are exactly the needed operations. The small count is reasonable and neither tool is redundant.
The server covers the full diff-then-apply lifecycle: it can identify mismatches, removed items, and new items, and then safely write corrections back, including controlled removal handling. Parametrized categories, dry-run preview, and output_path prevent dead ends.
Maintenance
Related MCP Connectors
Reconcile business documents, inspect exact differences and evidence, and export reports.
Auditable construction takeoffs with locked waste and conservative purchase rounding.
Mechanically reconcile supplied purchase-order lines, invoice lines and goods receipts under expl...
Preflight approved takeoffs with existing credits; review source gaps and export reviewed estimates.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to safely ingest, inspect, edit, and export manufacturing documents (Excel, PDF, Word, Markdown) with controlled patch workflows and MES entity extraction.23MIT
- AlicenseNot gradedqualityCmaintenanceEnables an AI assistant to run pre-ingest QA on utility power-grid GIS exports: score readiness, list issues with coordinates, reconcile registers against survey/LiDAR detections, map codes to library types, and draft a data request. It exposes the same checks, reconciliation and reporting operations as callable tools so a deployment engineer can work conversationally in any MCP client.MIT
- FlicenseNot gradedqualityAmaintenanceEnables 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.-
- AlicenseNot gradedqualityBmaintenanceIt exposes typed tools for DXF-to-Engineering-IR parsing, allowlisted modification planning, deterministic validation, preview/diff, and readback verification, while keeping approval and execution out of the agent’s control.MIT