Content
# 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.
[](https://github.com/andretaki/hazmat-cfr-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/hazmat-cfr-mcp)
[](https://modelcontextprotocol.io/)
[](LICENSE)
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
```bash
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](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](https://www.ecfr.gov/current/title-49).
## Install and run
```bash
npx hazmat-cfr-mcp # MCP stdio server
npx hazmat-cfr lookup UN1090 # CLI
```
From a clone:
```bash
git clone https://github.com/andretaki/hazmat-cfr-mcp.git
cd hazmat-cfr-mcp
npm install
npm run build
npm run demo
```
CLI:
```bash
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
```json
{
"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:
```json
{ "query": "UN1090" }
```
## Library use
```ts
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
```bash
# bump ECFR_SNAPSHOT_DATE in src/data/snapshot.ts, then:
npm run ingest -- --fresh
npm test
```
See [docs/data-pipeline.md](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
```bash
npm test
npm run typecheck
npm run scan:secrets
```
## Maintainer
Andre Taki — [Alliance Chemical](https://alliancechemical.com) — andre@alliancechemical.com
## License
MIT — the underlying 49 CFR text is a public-domain work of the U.S. government.
