hazmat-cfr-mcp

hazmat-cfr-mcp

The complete 49 CFR 172.101 Hazardous Materials Table, as an MCP tool for AI agents — every field cited to a pinned eCFR revision.

Give Claude, Cursor, Codex, and other MCP clients a DOT hazmat lookup, classification, and validation tool backed by the entire Hazardous Materials Table — not a sample.

Ask an agent:

Can I ship 60 L of acetone on a cargo-only aircraft? What are its label, packing, and special-provision requirements?

It returns the proper shipping name, hazard class, packing group, label codes, packaging references, aircraft limits, vessel stowage, decoded special provisions, and CFR citations — in structured JSON.

Use it two ways:

• hazmat-cfr-mcp — MCP stdio server for agents
• hazmat-cfr — local CLI for humans, tests, and scripts

No API keys. No customer data. No carrier contracts. No NMFC. Public CFR only.

What's in the box

• ~2,700 Hazardous Materials Table entries (49 CFR 172.101) — every UN/NA entry plus Forbidden materials, ingested directly from the official eCFR.
• Special-provision decoding — all ~420 Column 7 codes (49 CFR 172.102: numeric, A, B, IB, IP, N, R, T, TP, W) expanded into their regulatory text.
• Legend decoding — Column 1 symbols (+ A D G I W), Column 10A vessel stowage categories, and Columns 8A–8C packaging references resolved to part-173 sections.
• Pinned to a dated eCFR snapshot so every answer is reproducible and citable to an exact revision.
• A curated synonym/CAS layer so "IPA", "muriatic acid", or "bleach" resolve — kept clearly separate from regulatory data.

10-second try

npx -y hazmat-cfr-mcp --help
npx -y hazmat-cfr lookup UN1088          # not in any "sample" — the whole table is here
npx -y hazmat-cfr decode-sp IB2 T8 A3

Why this exists

Foundation models are weak at regulated shipping details. They may know what acetone is, but they should not guess whether a shipping description is complete, what IB2 means, or which CFR field backs a label requirement.

This server gives agents an explicit, cited, complete hazmat tool surface so they answer with the regulation instead of a hallucination.

Accuracy & verification

This is a compliance-adjacent tool, so correctness is enforced by the build, not by hope:

• The dataset is generated from the eCFR versioner API and committed to the repo (see docs/data-pipeline.md). It is never hand-edited.
• The ingest fails if any special-provision code referenced by the table does not resolve in 172.102 (documented source errata, e.g. IP16, are resolved to an explicit "referenced but not defined" note — never fabricated).
• test/data-integrity.test.ts re-checks entry counts, structural validity, referential integrity, and ~22 hand-verified spot-checks on every run.
• The parsers are unit-tested against fixtures in test/fixtures/.

⚠️ Disclaimer. This is an informational aid that surfaces public CFR text. It is not legal advice, not a compliance certification, and not a substitute for a trained hazmat employee. Always verify any shipping decision against the current eCFR.

Install and run

npx hazmat-cfr-mcp            # MCP stdio server
npx hazmat-cfr lookup UN1090  # CLI

From a clone:

git clone https://github.com/andretaki/hazmat-cfr-mcp.git
cd hazmat-cfr-mcp
npm install
npm run build
npm run demo

CLI:

npx hazmat-cfr lookup UN1090
npx hazmat-cfr requirements UN1830          # everything to ship it, in one call
npx hazmat-cfr placard 2.3
npx hazmat-cfr validate "UN1090, Acetone, 3, PG II"
npx hazmat-cfr segregation 3 5.1 8
npx hazmat-cfr lq 3 II 1000 12 true
npx hazmat-cfr decode-sp IB2 T8 A3
npx hazmat-cfr decode-pkg nonBulk 202

MCP client config

{
  "mcpServers": {
    "hazmat-cfr": {
      "command": "npx",
      "args": ["hazmat-cfr-mcp"]
    }
  }
}

For a local checkout, point command at node and args at dist/server.js.

Tools

Tool	Purpose
lookup_hazmat_entry	Look up by UN/NA number or proper shipping name; returns matching entries with decoded symbols and special provisions.
get_shipping_requirements	One call → everything to ship a material: identity, labels, decoded packaging, special provisions, vessel stowage, placard, and citations.
classify_shipping_description	Parse free text into structured fields, then validate it.
validate_basic_hazmat_description	Validate structured fields against the full 172.101 table.
get_label_requirements	Return hazard label codes and caveats.
get_placard	49 CFR 172.504 placard name + quantity threshold for a hazard class.
check_basic_segregation	Conservative pairwise segregation findings (49 CFR 177.848 subset).
check_limited_quantity_eligibility	Conservative Class 3/Class 8 LQ-candidate screen.
decode_special_provision	Expand Column 7 codes (e.g. IB2, T8, A3) into 49 CFR 172.102 text.
decode_packaging_reference	Resolve a Column 8A/8B/8C value to its part-173 section.
explain_cfr_source	Explain which public CFR source backs a field or rule.

Example call:

{ "query": "UN1090" }

Library use

import { defaultCatalog, decodeSpecialProvisions, ECFR_SNAPSHOT_DATE } from "hazmat-cfr-mcp";

const acetone = defaultCatalog.lookup("UN1090");
const provisions = decodeSpecialProvisions(acetone.entries[0].specialProvisions);
console.log(`Backed by eCFR snapshot ${ECFR_SNAPSHOT_DATE}`);

Refreshing the data

# bump ECFR_SNAPSHOT_DATE in src/data/snapshot.ts, then:
npm run ingest -- --fresh
npm test

See docs/data-pipeline.md for the full pipeline.

Non-goals

Not legal advice; not a replacement for trained hazmat employees; not a full compliance certification engine; not NMFC classification; not carrier contract/tariff analysis. No private customer data, contract rates, or internal business records belong in this repo.

Safety

npm test
npm run typecheck
npm run scan:secrets

Maintainer

Andre Taki — Alliance Chemical — [e-mail]

License

MIT — the underlying 49 CFR text is a public-domain work of the U.S. government.