Hazmat Cfr Mcp

io.github.andretakiPublished by GitHub account andretakiv0.3.0Updated Oct 24, 2026

Complete 49 CFR 172.101 hazmat table lookup with special-provision decoding, cited to eCFR.

VerifiedSTDIODesktop onlyKnowledge & MemoryBusiness & Commerce

Overview

AI-generated overview

A local MCP server that gives an assistant the full 49 CFR 172.101 hazardous materials table for DOT hazmat lookup, classification and validation, cited to eCFR

What you can do
Look up hazmat entries by UN/NA number or proper shipping name, with decoded symbols and special provisions, and get full shipping requirements in one call (labels, packaging, stowage, placards, citations). Parse and validate shipping descriptions, and check label requirements, placards, segregation and limited-quantity eligibility. Decode Column 7 special provisions and Column 8 packaging references into their regulatory text. Explain which public CFR source backs a field or rule.
When to use it
Useful when an assistant needs to answer shipping questions about hazardous materials — proper shipping names, hazard classes, packing groups, labels, aircraft limits, vessel stowage — and should cite the regulation rather than guess. Aimed at logistics, shipping and compliance drafting work, not at replacing a trained hazmat employee.
Requirements
Runs as a local stdio process on the user's machine, started via npx with the hazmat-cfr-mcp package (Node.js required). No API keys, accounts or environment variables are declared; the dataset ships with the package and is pinned to a dated eCFR snapshot.
Before you install
Informational aid only: the README states it is not legal advice, not a compliance certification and not a substitute for a trained hazmat employee, and that shipping decisions should be verified against the current eCFR. Data is pinned to a snapshot, so it may lag later regulatory changes. Read-only lookup and validation; no data is sent to third parties.

Installation

In SourceWeft

  1. Open Hazmat Cfr Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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.

[CI] [npm] [MCP] [License: MIT]

[hazmat-cfr-mcp demo]

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 --helpnpx -y hazmat-cfr lookup UN1088          # not in any "sample" — the whole table is herenpx -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

bash
npx hazmat-cfr-mcp            # MCP stdio servernpx hazmat-cfr lookup UN1090  # CLI

From a clone:

bash
git clone https://github.com/andretaki/hazmat-cfr-mcp.gitcd hazmat-cfr-mcpnpm installnpm run buildnpm run demo

CLI:

bash
npx hazmat-cfr lookup UN1090npx hazmat-cfr requirements UN1830          # everything to ship it, in one callnpx hazmat-cfr placard 2.3npx hazmat-cfr validate "UN1090, Acetone, 3, PG II"npx hazmat-cfr segregation 3 5.1 8npx hazmat-cfr lq 3 II 1000 12 truenpx hazmat-cfr decode-sp IB2 T8 A3npx 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

ToolPurpose
lookup_hazmat_entryLook up by UN/NA number or proper shipping name; returns matching entries with decoded symbols and special provisions.
get_shipping_requirementsOne call → everything to ship a material: identity, labels, decoded packaging, special provisions, vessel stowage, placard, and citations.
classify_shipping_descriptionParse free text into structured fields, then validate it.
validate_basic_hazmat_descriptionValidate structured fields against the full 172.101 table.
get_label_requirementsReturn hazard label codes and caveats.
get_placard49 CFR 172.504 placard name + quantity threshold for a hazard class.
check_basic_segregationConservative pairwise segregation findings (49 CFR 177.848 subset).
check_limited_quantity_eligibilityConservative Class 3/Class 8 LQ-candidate screen.
decode_special_provisionExpand Column 7 codes (e.g. IB2, T8, A3) into 49 CFR 172.102 text.
decode_packaging_referenceResolve a Column 8A/8B/8C value to its part-173 section.
explain_cfr_sourceExplain 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 -- --freshnpm 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

bash
npm testnpm run typechecknpm run scan:secrets

Maintainer

Andre Taki — Alliance Chemical — [email protected]

License

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

Source: README.md at commit c733ac6

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts