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 agentshazmat-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.tsre-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 — andre@alliancechemical.com
License
MIT — the underlying 49 CFR text is a public-domain work of the U.S. government.