# FreightUtils MCP server

> Provides AI agents with deterministic freight reference data, dangerous goods (ADR) validation, customs codes, and logistics calculations.

- Repository: https://github.com/SoapyRED/freightutils-mcp
- Page: https://hostedmcp.org/servers/soapyred/freightutils-mcp
- Transport: stdio, remote
- Stars: 8
- License: MIT
- Latest version: 2.34.4

## Install

### Claude Code

```sh
claude mcp add freightutils-mcp -- npx -y freightutils-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "freightutils-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "freightutils-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "freightutils-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "freightutils-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"freightutils-mcp","type":"stdio","command":"npx","args":["-y","freightutils-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "freightutils-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "freightutils-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add freightutils-mcp -- npx -y freightutils-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.freightutils-mcp]
command = "npx"
args = ["-y", "freightutils-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user freightutils-mcp npx -- -y freightutils-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "freightutils-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "freightutils-mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `FREIGHTUTILS_API_KEY` | no | no |  |

## Tools (27)

- `cbm_calculator`: Cubic metres (CBM) of a shipment from per-piece dimensions in cm and a piece count, with cubic feet, litres and cubic inches. Volume only: for air billing weight from the same dimensions use chargeable_weight_calculator, for multi-line totals consignment_calculator, for one unit conversion unit_converter, for a full composite analysis shipment_summary. Deterministic; totals are computed from unrounded figures and rounded only for display. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. (read-only)
- `chargeable_weight_calculator`: Air freight chargeable weight — the greater of actual gross weight and volumetric weight, which is what airlines bill. The dimensions are per piece and gross_weight_kg is the TOTAL for all pieces; factor is the volumetric divisor (default 6000, the IATA standard; express integrators typically use 5000). Air only: sea W/M is consignment_calculator with mode=sea; volume alone is cbm_calculator; multi-line loads in any mode consignment_calculator; the equipment the freight flies in uld_lookup. Deterministic; totals are computed from unrounded figures and rounded only for display. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. (read-only)
- `ldm_calculator`: Loading metres (LDM) for European road freight — how much trailer length a pallet load occupies (1 LDM = 1 linear metre of a 2.4 m-wide trailer; a standard artic is 13.6 LDM) — and whether it fits. Provide a pallet preset OR custom length_mm + width_mm; omitting both errors. fits is true only when the load fits the vehicle's length, its pallet floor positions and, when weight_kg is given, its max payload; without weight_kg the payload is not checked. For the trailer specs behind the presets use vehicle_lookup; for boxes onto one pallet pallet_fitting_calculator; for mixed lines consignment_calculator. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. (read-only)
- `adr_lookup`: Look up the full European road dangerous-goods (ADR 2025) Table A entry for a substance — all 20 columns, from class, packing group and labels through special provisions, limited/excepted quantities, packing instructions, tank codes, carriage provisions, transport category, tunnel restriction code and hazard identification number — and what each of those codes means (resolved_codes). 2,939 entries across all 9 classes, from UNECE ADR 2025. Provide exactly ONE of: un_number (every packing-group variant of it; "1203", "UN1203" and "un 1203" are equivalent; explosives keep their leading zero), search (partial proper shipping name), hazard_class, or un_numbers (batch). A search with no hits errors with the closest names. For an LQ/EQ quantity check use adr_lq_eq_check; for 1.1.3.6 small-load points adr_exemption_calculator; for an identifier of unknown kind resolve_reference. Editions: edition ("2025" | "2027") and as_of (YYYY-MM-DD) choose the ADR edition — edition wins, else the date picks it (ADR 2025 before 2027-01-01, ADR 2027 from then; ADR 2025 may still be applied until 2027-06-30). An answer on a named edition carries adr_edition; neither sent, the answer is ADR 2025 until 2027-01-01. edition ("2025" | "2027") and as_of choose the ADR edition; neither sent, ADR 2025 until 2027-01-01. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. A factual compilation of the ADR table, not legal or compliance advice; classification remains the consignor's responsibility. (read-only)
- `adr_exemption_calculator`: ADR 1.1.3.6 "small load" exemption points for a dangerous-goods road load, and whether it qualifies; points = quantity x the transport category multiplier. The rule (1.1.3.6.2), for dangerous goods carried in packages: goods of ONE transport category qualify when their TOTAL on the transport unit stays within that category's 1.1.3.6.3 column (3) maximum (category 1: 20, 2: 333, 3: 1,000 kg or L; 4 unlimited; 0: 0); goods of DIFFERENT categories qualify when the 1.1.3.6.4 points sum does not exceed 1,000. Transport category 0 can never use the exemption. For limited/excepted quantity relief use adr_lq_eq_check; for a substance's row and variant_index adr_lookup; for the whole ADR picture of a load (tunnels, documents, plates) adr_consignment_check. Send un_number + quantity for one substance OR items[] for a load — never both: a single-substance field sent beside items[] is refused, never dropped. Quantities are kg or litres per the substance's ADR unit; a quantity of 0 means not carried, and a load of nothing but zeros is refused. A UN number whose Table A rows disagree needs packing_group or variant_index, else that line has no verdict (AMBIGUOUS_UN_VARIANT with candidates[]) — never a guessed row. An ID-prefixed air-only number (e.g. "ID8000") is counted out of 1.1.3.6 only with icao_limited_quantity: true on that line, otherwise BLOCKED. Without that statement the ID line is BLOCKED (items[].entry_required true) and the load has no verdict unless the other lines settle it. A gross mass (basis "gross") is only an upper bound: send the net quantity. edition ("2025" | "2027") and as_of choose the ADR edition; neither sent, ADR 2025 until 2027-01-01. Such an answer headlines the transitional basis that clears the load, names it, gives basis_until (the last day it may be applied) and puts the strict ADR 2027 figure beside it (strict_adr_2027: basis, total_points, exempt, has_category_zero, has_quantity_exceedance). Fields are checked by name: a field the tool does not read is refused with a tool error naming it and listing the accepted ones, never ignored. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. A calculation over reference data, not legal advice: 1.1.3.6 relieves goods carried in packages only (not in bulk or in tanks), and exempt loads keep core duties; verify against the current UNECE ADR text. (read-only)
- `airline_lookup`: Find airlines (6,356) by name, IATA code, ICAO code, AWB prefix (the first 3 digits of an air waybill number, e.g. 176 = Emirates) or country. Provide ONE parameter: query is a ranked fuzzy search; iata / icao / prefix / country are exact filters. Searches carriers, not airports — for airports use airport_lookup; to check an AWB number's check digit use validate. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. Provenance pending independent verification — confirm operationally critical codes with IATA/ICAO or the carrier. (read-only)
- `airport_lookup`: Look up an airport by IATA code ("LHR"), ICAO code ("EGLL") or free-text name/city search (OurAirports, public domain). Covers 86,281 airports worldwide (OurAirports, public domain, cross-checked vs OpenFlights + Wikidata). Provide ONE of iata, icao or query; ambiguous name searches return ranked candidates; an unknown code errors. For airports near a coordinate use nearest_airport; for carriers and AWB prefixes airline_lookup; for general transport locations unlocode_lookup. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. Reference data only — not for navigation. (read-only)
- `nearest_airport`: The airports nearest a latitude/longitude you provide, sorted by great-circle distance (distance_km on each). Searches 86,281 airports (OurAirports, public domain). By default only airports with scheduled airline service and an IATA code are ranked — never a heliport or a closed field; include_all: true ranks every type except closed fields. Does NOT geocode place names — pass coordinates you already hold; nothing is stored. For an exact code or name lookup use airport_lookup; for named transport locations unlocode_lookup. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. Reference data only — not for navigation. (read-only)
- `resolve_reference`: Resolve an arbitrary freight identifier — one opaque string in, typed and cited candidates out. Use when you hold one identifier-ish token ("176", "UN1845", "NLRTM", "FOB", "22G1", "MSKU1100810", "D/E", "TU9") and do not know what kind of identifier it is: each candidate names its entity type and carries the api_url and canonical_url of its full record. q is ONE identifier (max 32 chars), or an fu: identifier (fu_id or fu_version_id, up to 200 chars), which resolves to exactly its one record or to none. Colliding grammars return several ranked candidates, never a silent guess; zero candidates is a valid result. Single-token resolution, not free-text extraction — pass one identifier, not a manifest line. The lookups it resolves into: adr_lookup, airline_lookup, airport_lookup, unlocode_lookup, hs_code_lookup, incoterms_lookup, container_lookup, uld_lookup, validate. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. (read-only)
- `container_lookup`: ISO shipping-container specifications for 10 types (20ft/40ft standard, 40ft and 45ft high-cube, reefer, open-top and flat-rack), with optional load-fit maths. type (a slug such as "40ft-high-cube", the ISO size-type code "45G1" or the short form "40HC") gives one record; omit it to list all 10; add item dimensions to compute how many items fit. For a container NUMBER's check digit use validate; for the air-freight equivalent uld_lookup; for the cargo volume cbm_calculator / consignment_calculator. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. Manufacturer-typical specs, provenance pending — confirm against the carrier's equipment guide. (read-only)
- `hs_code_lookup`: Search the 6,936 codes of the WCO Harmonized System (HS 2022), the 6-digit international customs classification (2 digits chapter, 4 heading, 6 subheading). Provide ONE of: query (free-text description), code (2-6 digits, dots or spaces ignored; returns the code with its hierarchy) or section (Roman numeral I-XXI). Behavior: read-only; description search runs first against the HS 2022 descriptions (UN Comtrade H6), on whole words only (a word inside a longer word never matches); when none contains the words, or the best match is weak, it asks the UK Trade Tariff search references (HMRC's index of everyday goods names) and serves their answer, so "laptop" finds 847130, "computers" heading 8471 and "charger" heading 8504. A description search matches whole words, then asks HMRC's everyday goods names at medium confidence; count 0 with an empty results[] is a valid answer (NO_MATCH). For UK duty/VAT on a code use uk_duty_calculator; for ENS goods-description screening ics2_check. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. The 6-digit level only — national tariff lines and duty rates are set per country; indicative, not a binding ruling. (read-only)
- `incoterms_lookup`: The 11 Incoterms 2020 rules — who pays for transport, insurance and customs clearance, and where risk transfers from seller to buyer. code gives one rule; category (any_mode | sea_only) filters; neither lists all 11. An unknown code errors with the valid list; DAT names its successor, DPU. Related: uk_duty_calculator (takes an incoterm when composing the CIF value), shipment_summary. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. Summarised guidance; the ICC publication is the binding text. (read-only)
- `pallet_fitting_calculator`: How many identical boxes fit on one pallet: boxes per layer (trying 90-degree rotation when allowed), layers within the max height, totals, footprint and volume utilisation (volume_utilisation_percent), capped in whole layers by max_payload_kg. One box size in aligned rows — no interlocked or mixed patterns. For pallets into trailer length use ldm_calculator; pallet capacity per vehicle vehicle_lookup; pallets into containers container_lookup. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. A theoretical best-effort fit — carton strength, overhang and load stability are not modelled. (read-only)
- `unit_converter`: Convert freight weight, volume and length units, plus chargeable_kg (air volumetric weight at the IATA 6,000 divisor) and freight_tonnes (sea W/M, 1 CBM = 1 freight tonne), both only FROM cbm. Cross-dimension conversions (e.g. kg to litres) and a negative value are refused. For dimensions to volume use cbm_calculator; for air billing weight with pieces and a custom divisor chargeable_weight_calculator. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. (read-only)
- `consignment_calculator`: Per-line and grand totals for a multi-item mixed consignment: CBM, loading metres, volumetric weight and the mode's chargeable figure (air chargeable weight, sea revenue tonnes, road LDM), plus advisory flags (implausible density, mode/option mismatch, dangerous goods by UN number, container/AWB check digits). Send mode (sea | air | road, default road) and lines[] (each line with its own dimension and weight units), or the legacy flat items[] in cm and kg. For a vehicle/container suggestion and duty estimates use shipment_summary; for one figure cbm_calculator / chargeable_weight_calculator / ldm_calculator; for what a flagged UN number is adr_lookup. edition ("2025" | "2027") and as_of choose the ADR edition; neither sent, ADR 2025 until 2027-01-01. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. Flags are advisory and never state that a shipment is permitted or compliant; not regulatory, customs or dangerous-goods compliance advice. (read-only)
- `unlocode_lookup`: Search 116,086 UN/LOCODE transport locations — ports, airports, rail and road terminals, inland container depots and border crossings (5 characters: country + location, e.g. NLRTM = Rotterdam; "GB LHR" reads as GBLHR). code gives an exact record; query searches names, narrowed by country and function_type; an unknown code errors. For airport records with ICAO codes use airport_lookup; for airports near a coordinate nearest_airport. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. An administrative code list — confirm operational status and coordinates with the port or authority. (read-only)
- `uk_duty_calculator`: Estimate UK import duty and VAT for a commodity code from the LIVE GOV.UK Trade Tariff: CIF = customs_value + freight_cost + insurance_cost (GBP); duty = CIF x the rate for the origin country; VAT on the duty-inclusive value. commodity_code must be the declarable 10 digits: a 6- or 8-digit code is refused — never padded with zeros — with the declarable codes beneath it. To find the code first use hs_code_lookup; for who pays these costs incoterms_lookup. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. An estimate, not a customs ruling — confirm with a customs broker or HMRC. (read-only)
- `shipment_summary`: Composite shipment analysis in one call: volume (CBM), gross and chargeable weight, and by mode road LDM with pallet floor positions and a suggested vehicle, air volumetric weight, or sea revenue tonnes with a suggested container; plus dangerous-goods presence for items with un_number and UK duty estimates for items with hs_code + customs_value. weight and customs_value are PER ITEM; adr_quantity is the TOTAL for the dangerous-goods line, all pieces together. An item with no stackable flag is not stacked. Sections that cannot run surface in warnings instead of failing the call. Its result uses camelCase field names (legacy shape). For canonical snake_case lines[] totals with advisory flags use consignment_calculator; single figures cbm_calculator, chargeable_weight_calculator, ldm_calculator; ldm_calculator, adr_lookup and uk_duty_calculator are the engines it calls. edition ("2025" | "2027") and as_of choose the ADR edition; neither sent, ADR 2025 until 2027-01-01. Fields are checked by name: a field the tool does not read is refused with a tool error naming it and listing the accepted ones, never ignored. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. A planning summary, not a quotation or compliance determination. (read-only)
- `uld_lookup`: Air-cargo ULD (unit load device) specifications — 16 types: lower-deck containers (AKE/LD3 and family), main-deck pallets (PMC, PAG and family) and temperature-controlled units. type as an IATA code ("AKE"), slug ("ake-ld3") or the record's own name ("LD3" → AKE) gives one record; omit it to list all 16; category and deck filter. Pallet records have no internal dimensions — read max_build_up_height_cm, and do not multiply dimensions for a volume. For the sea-freight equivalent use container_lookup; for what the cargo inside is billed at chargeable_weight_calculator; for whose aircraft it flies on airline_lookup. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. Provenance is pending, not verified (treat tare_weight with particular caution); confirm operationally critical dimensions with the carrier. (read-only)
- `vehicle_lookup`: Road-freight vehicle and trailer specifications — 17 types: EU articulated trailers, US 53ft/48ft dry vans, rigid trucks (7.5-26 t) and vans; internal dimensions, payload and gross weights, pallet capacity, axles. slug gives one record; omit it to list all 17; category (articulated | rigid | van) and region (EU | US) filter. For whether a pallet load fits use ldm_calculator; also pallet_fitting_calculator and consignment_calculator. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. Typical specs, provenance pending — legal payload is set by the vehicle's plated weights. (read-only)
- `get_subscribe_link`: Return the FreightUtils pricing page URL with the Pro plan's request limit (50,000 per month) and price. Use when the user asks about FreightUtils plans, pricing or API limits. A static local response — no API call, never rate-limited, no account or payment action; the user opens the URL in a browser. (read-only)
- `adr_lq_eq_check`: Whether dangerous goods qualify for ADR Limited Quantity (LQ, ADR 3.4) or Excepted Quantity (EQ, ADR 3.5) relief, item by item. Send mode ("lq" or "eq") and 1-20 items, each with un_number, quantity per INNER packaging (not the whole load) and unit (ml or L for liquids, g or kg for solids); inner_packaging_qty adds the EQ per-outer check. A mass against a volume limit (or the reverse) cannot be compared: that item is inconclusive — send the unit given by lq_limit_unit. A UN number whose Table A rows disagree needs packing_group or variant_index, else no verdict for it (AMBIGUOUS_UN_VARIANT with candidates[]). For the 1.1.3.6 load-points route use adr_exemption_calculator; for the per-substance LQ/EQ values and variant_index adr_lookup. edition ("2025" | "2027") and as_of choose the ADR edition; neither sent, ADR 2025 until 2027-01-01. Fields are checked by name: a field the tool does not read is refused with a tool error naming it and listing the accepted ones, never ignored. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. A quantity-threshold check only — packaging, marking and documentation conformity are not assessed; not legal advice, verify against the current UNECE ADR text. (read-only)
- `emissions_calculator`: Estimate freight transport greenhouse-gas emissions (kgCO2e) for one shipment leg, per ISO 14083:2023 / GLEC Framework v3.2: mass x distance x a published emission-intensity factor (DEFRA, EPA or ADEME by region). Pass ACTUAL GROSS MASS, not chargeable/volumetric weight, and a distance you provide — this tool does NOT route, geocode or compute distances. The fleet-average factor already includes average empty running: do not add an empty-return leg. An unknown mode/sub_mode/region returns available:false with the covered options. Distinct from cbm_calculator / ldm_calculator / chargeable_weight_calculator, which size or bill a shipment. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. A best-effort reference estimate, not a verified or audited carbon report. (read-only)
- `validate`: Validate freight identifiers by their public check-digit algorithms: shipping container numbers (ISO 6346), air waybill numbers (IATA modulus-7) and IMO ship numbers. text finds and validates every identifier in a string; value + type validates one (value without type is refused); type "consignment" with consignment validates a consignment object. An AWB names its airline only when one record holds the prefix; otherwise airline_candidates[] lists every holder, never a guessed carrier. AWB: airline prefix + the airline from the AWB-prefix dataset when ONE record holds the prefix — when several do (e.g. 020: Lufthansa and Lufthansa Cargo), airline is null and airline_candidates[] lists every holder with airline_note saying why, never a guessed carrier. For container TYPE specs use container_lookup; for the AWB-prefix dataset airline_lookup. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. Structural only — a valid check digit means well-formed, NOT that the container, shipment or vessel exists. (read-only)
- `ics2_check`: Check a goods description against the official EU ICS2 stop-words list — terms too vague or generic for an entry summary declaration (ENS) goods description. A standalone stop-word means automatic rejection, an embedded one means make the description more specific; clean=true means no listed term matched, not that it will be accepted. For commodity codes use hs_code_lookup; for duty/VAT uk_duty_calculator. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. Strictly a reference check — not an ENS filing, not a customs-compliance determination, not legal advice. (read-only)
- `adr_consignment_check`: One call on the consignment object for the ADR picture of a road load: the 1.1.3.6 small-load verdict, the limited / excepted quantity check of each line, the tunnel restriction code of the whole load against the tunnels on the route, each line's transport-document entry, mixed loading (7.5.2, with the foodstuffs precautions of 7.5.4), and the vehicle side — orange-coloured plates and placards (5.3), the documents, fire extinguishers and equipment on the transport unit (8.1), and driver training (8.2); and the UN packaging mark of each line (6.1.3.1). The rules are page-cited to the free UNECE ADR 2025 publication. For the 1.1.3.6 check alone use adr_exemption_calculator; LQ / EQ alone adr_lq_eq_check; a row's columns adr_lookup. Send lines[] (un_number, quantity {value, unit, basis} and, where they apply, packing_group / variant_index, packages with un_mark, inner_packaging) and optionally journey, vehicle and crew; journey.date is the default as_of, and an as_of that contradicts it is refused. A check whose input is not sent is conditional, the input named in missing_inputs — never assumed. status is pass | fail | conditional | insufficient_data; a relief that does not apply is not_applicable, not fail. edition ("2025" | "2027") and as_of choose the ADR edition; neither sent, ADR 2025 until 2027-01-01. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. Not checked: whether the packaging kind is one the packing instruction allows, IBC / large-packaging marks, the vehicle approval of Part 9, the elevated temperature mark (5.3.3), handling and stowage (7.5.7). Not legal advice, verify against the current UNECE ADR text. (read-only)
- `booking_check`: Check a road booking before the job is created: from the booking's fields it returns three lists — MISSING (fields the booking lacks, each with the calculation that needs it), NEEDS (volume, gross and chargeable weight, loading metres, whether the load fits the booked vehicle, the ADR consignment check's result for dangerous goods) and STOPS (a code that does not resolve, a load the vehicle cannot take, a dangerous-goods check that fails or refuses) — and a verdict: no_blocker_found, missing_information or blocker_found. Use it as an intake agent's gate between reading a booking and creating the job; for dangerous goods alone use adr_consignment_check, for volume and chargeable weight alone consignment_calculator. Road only in this version. It composes the existing calculators and lookups and adds no rule; every line cites the engine it came from. Short by default; detail: true adds each engine's full answer. Nothing is stored; party names, addresses and free text are ignored and never echoed. Not a booking system, no rate, route, drivers' hours or legal clearance; a clean answer means no engine found a blocker in the fields sent. Rate-limited: a limit error carries reset_at, the UTC time the allowance resets. (read-only)

## FAQ

### What kind of data does FreightUtils provide?

It provides source-backed dangerous-goods, customs, location, and freight-calculation data including ADR, HS, UN/LOCODE, and IATA-regulated airline prefixes.

### Does the server provide legal or booking advice?

No, it is for reference only and does not provide filing, booking, or legal advice.

### How can I get a receipt for a check?

A receipt is stored when the package runs with an API key (FREIGHTUTILS_API_KEY).

### Can the server handle multiple codes at once?

Yes, several tools support batch inputs, such as up to 50 codes for UN/LOCODE, airport, airline, or HS code lookups.
