io.github.SoapyRED/freightutils

Official24 tools

by SoapyRED · TypeScript

FreightUtils MCP Server

Neutral freight reference layer for AI agents: ADR, HS, airlines, UN/LOCODE, ULDs, freight math

Reference data for freight operations including ADR, HS codes, airlines, and logistics.

Topics

ai-agentsfreightlogisticsmcpmodel-context-protocol

Captured live from the server via tools/list.

cbm_calculator

Calculate cubic metres (CBM) for a shipment. CBM is the standard volume unit in international shipping. 1 CBM = 1m x 1m x 1m = 1,000 litres. Ocean freight carriers price per "freight tonne" (1 CBM or 1,000 kg, whichever is greater).

Parameters (4)

length_cmnumberrequired
Length in centimetres
width_cmnumberrequired
Width in centimetres
height_cmnumberrequired
Height in centimetres
piecesinteger
Number of identical pieces (default: 1)

chargeable_weight_calculator

Calculate air freight chargeable weight (volumetric vs actual). Airlines charge the greater of actual weight or volumetric weight. IATA standard factor: 6,000 (1 CBM = 166.67 kg). A ratio > 1.0 means volumetric (light for its size).

Parameters (6)

length_cmnumberrequired
Length in centimetres
width_cmnumberrequired
Width in centimetres
height_cmnumberrequired
Height in centimetres
gross_weight_kgnumberrequired
Actual gross weight in kilograms
piecesinteger
Number of identical pieces (default: 1)
factorinteger
Volumetric divisor (default: 6000)

ldm_calculator

Calculate loading metres (LDM) for road freight. LDM measures trailer utilisation. European trailers are 13.6m long, 2.4m wide. Supports pallet presets (euro, uk, half, quarter) and vehicles (artic, rigid10, rigid75, luton).

Parameters (9)

palletstring
Pallet preset
length_mmnumber
Custom pallet length in mm
width_mmnumber
Custom pallet width in mm
quantityinteger
Number of pallets (default: 1)
stackableboolean
Can pallets be stacked?
stack_heightinteger
Stack height 2 or 3
weight_kgnumber
Weight per pallet in kg
vehiclestring
Vehicle type
vehicle_length_mnumber
Custom vehicle length in m

adr_lookup

Look up dangerous-goods (hazmat) reference data from the ADR 2025 dataset — 2,939 entries across all 9 hazard classes. Provide exactly one of: un_number (exact lookup, returns every packing-group variant), search (case-insensitive partial match on the proper shipping name, min 2 characters), or hazard_class (all entries in that class). Returns proper shipping name, hazard class, classification code, packing group, labels, special provisions, limited/excepted quantity codes, transport category, tunnel restriction code, and hazard identification number for each match. Returns reference data only — it does not assess or certify regulatory compliance for a shipment; an empty result set means nothing matched.

Parameters (3)

un_numberstring
Exact UN number — 4 digits, optionally "UN"-prefixed; explosives keep their leading zero. Examples: "1203", "UN1203", "0004".
searchstring
Case-insensitive partial match on the proper shipping name (min 2 characters). Example: "acetone".
hazard_classstring
Filter by ADR hazard class and its divisions. Examples: "3" (flammable liquids), "6.1" (toxic), "8" (corrosive), "1.4" (an explosives division).

adr_exemption_calculator

Calculate ADR 1.1.3.6 exemption. Points = quantity x multiplier per transport category. Total <= 1,000 = exempt from full ADR requirements. For single substance: provide un_number + quantity. For mixed loads: provide items array.

Parameters (3)

un_numberstring
UN number for single check (4 digits, optionally "UN"-prefixed)
quantitynumber
Quantity in kg/L
itemsarray
Array of items for mixed-load check

airline_lookup

Search 6,352 airlines by name, IATA/ICAO code, AWB prefix, or country. AWB prefixes are 3-digit codes on air waybills identifying the carrier (e.g., 176 = Emirates).

Parameters (5)

querystring
General search (name, code, prefix or country — min 2 chars)
iatastring
Exact IATA code (2 alphanumeric chars)
icaostring
Exact ICAO code (3 letters)
prefixstring
AWB prefix (3 digits)
countrystring
Filter by country name (min 2 chars)

airport_lookup

Look up an airport by IATA code (3 letters, e.g. "LHR"), ICAO code (4 chars, e.g. "EGLL"), or free-text name / city search (e.g. "heathrow", "chicago"). Returns the full record: IATA + ICAO, name, type (large/medium/small/heliport/closed/seaplane), municipality, region, country, latitude/longitude and elevation. Optional type filter; ambiguous name searches return ranked candidates (exact codes first, then larger airports). Covers 85,555 airports worldwide (OurAirports, public domain, cross-checked vs OpenFlights + Wikidata). Use when an agent has an airport code or name and needs the airport's identity, location or codes. Distinct from airline_lookup (which searches CARRIERS / AWB prefixes, not airports) and unlocode_lookup (general UN/LOCODE transport locations — ports, rail, road — of which airports are only one function). Reference data only — not for navigation; verify current codes with IATA / ICAO.

Parameters (4)

iatastring
Exact IATA code (3 letters)
icaostring
Exact ICAO / ident (4 chars)
querystring
Name / city / municipality search (min 2 chars)
typestring
Optional filter by airport type

nearest_airport

Find the airports nearest to a caller-provided latitude/longitude, sorted by great-circle (haversine) distance with distance_km on each result. Inputs: latitude, longitude (required), optional radius_km, max_results (1–50, default 10) and type filter (e.g. large_airport only). Coordinates are INPUT only — nothing is stored or logged. Searches 85,555 airports (OurAirports, public domain). Use when an agent already has a coordinate (a port, warehouse, city centre, or the user's location) and needs the closest airport(s). This tool does NOT geocode place names and does NOT compute routes — pass coordinates you already hold. Distinct from airport_lookup (exact code / name lookup, no distance) and unlocode_lookup (named transport-location search).

Parameters (5)

latitudenumberrequired
Latitude in decimal degrees (-90 to 90)
longitudenumberrequired
Longitude in decimal degrees (-180 to 180)
radius_kmnumber
Optional maximum distance in kilometres
max_resultsinteger
Max results to return (1–50, default 10)
typestring
Optional filter by airport type

container_lookup

Get ISO shipping container specs (10 types: 20ft, 40ft, 40ft HC, reefer, open-top, flat-rack, 45ft). Returns dimensions, capacity, weight limits, and pallet counts.

Parameters (1)

typestring
Container slug (e.g., "20ft-standard", "40ft-high-cube"). Omit to list all.

hs_code_lookup

Search 6,940 Harmonized System tariff codes. HS codes are 6-digit international product classification codes used for customs. Provide a search term or exact code.

Parameters (3)

querystring
Search by product description (min 2 chars)
codestring
Exact HS code (2-6 digits)
sectionstring
Browse by section (Roman numeral I–XXI)

incoterms_lookup

Look up Incoterms 2020 trade rules. 11 rules defining transport, insurance, customs responsibilities. 7 for any mode (EXW, FCA, CPT, CIP, DAP, DPU, DDP), 4 sea-only (FAS, FOB, CFR, CIF).

Parameters (2)

codestring
Incoterm code (3 letters, e.g., "FOB", "CIF")
categorystring
Filter by mode

pallet_fitting_calculator

Calculate how many boxes fit on a pallet with layers, rotation, and weight limits. Determines optimal arrangement and volume utilisation.

Parameters (10)

pallet_length_cmnumberrequired
Pallet length in cm
pallet_width_cmnumberrequired
Pallet width in cm
pallet_max_height_cmnumberrequired
Max stack height in cm
pallet_deck_height_cmnumber
Pallet deck height (default: 15cm)
box_length_cmnumberrequired
Box length in cm
box_width_cmnumberrequired
Box width in cm
box_height_cmnumberrequired
Box height in cm
box_weight_kgnumber
Box weight in kg
max_payload_kgnumber
Max pallet payload in kg
allow_rotationboolean
Allow 90-degree rotation (default: true)

unit_converter

Convert between freight units. Weight: kg, lbs, oz, tonnes, short_tons, long_tons. Volume: cbm, cuft, cuin, litres, gal_us, gal_uk. Length: cm, inches, m, feet, mm. Freight: cbm→chargeable_kg, cbm→freight_tonnes.

Parameters (3)

valuenumberrequired
Value to convert
fromstringrequired
Source unit — weight (kg, lbs, oz, tonnes, short_tons, long_tons), volume (cbm, cuft, cuin, litres, gal_us, gal_uk) or length (cm, inches, m, feet, mm)
tostringrequired
Target unit — any source unit, plus the freight targets chargeable_kg and freight_tonnes (only valid from cbm)

consignment_calculator

Calculate total CBM, loading metres (LDM), volumetric and mode-specific chargeable weight for a multi-item mixed consignment — per-line and grand totals, plus objective advisory flags. Provide a transport mode (sea | air | road) and either "lines" (canonical: each line has quantity, dims {l,w,h,unit}, weight {value,unit}, and optional description / hs_code / un_number / stackable) or the legacy flat "items" array (dimensions in cm, weight in kg). Air uses an IATA volumetric divisor (default 6000, settable via options.air_volumetric_divisor). Optionally pass options.container_number / options.awb_number for a check-digit sanity flag. Flags are advisory only — implausible density, mode/option mismatch, dangerous-goods presence by UN number against the ADR 2025 reference, and container/AWB check-digit validity. They never state that a shipment is permitted or compliant. Best-effort deterministic calculation and reference data only. Verify all inputs. Not regulatory, customs, or dangerous-goods compliance advice — you remain responsible for classification, documentation, and carrier acceptance.

Parameters (4)

modestring
Transport mode: sea | air | road (default road). Selects the chargeable-weight basis.
linesarray
Canonical consignment lines (preferred). Each: { quantity, dims:{l,w,h,unit}, weight:{value,unit}, optional description / hs_code / un_number / stackable }.
itemsarray
Deprecated flat alias — dimensions in cm, weight in kg. Prefer "lines". Provide lines OR items.
optionsobject
Optional: { air_volumetric_divisor, container_number, awb_number }.

unlocode_lookup

Search 116,129 UN/LOCODE transport locations worldwide. Covers seaports, airports, rail terminals, road terminals, inland clearance depots, and border crossings. Search by location name, code (e.g. GBLHR), country, or function type.

Parameters (5)

querystring
Search by name or code (e.g. "Rotterdam", "GBLHR", "LHR")
codestring
Exact UN/LOCODE lookup (e.g. "GBLHR", "NLRTM")
countrystring
ISO 2-letter country code filter (e.g. "GB", "NL")
function_typestring
Filter by location function
limitinteger
Max results (default 20)

uk_duty_calculator

Estimate UK import duty and VAT for a commodity code and origin country. Uses live GOV.UK Trade Tariff data. Returns CIF value, duty rate/amount, VAT rate/amount, total import taxes, and total landed cost. Flags preferential rates and import restrictions.

Parameters (6)

commodity_codestringrequired
UK tariff commodity code (6-10 digits)
origin_countrystringrequired
ISO 2-letter country of origin (e.g. "CN", "US")
customs_valuenumberrequired
Customs value in GBP
freight_costnumber
Freight cost in GBP (default 0)
insurance_costnumber
Insurance cost in GBP (default 0)
incotermstring
Incoterm basis

shipment_summary

Composite shipment summary — chains CBM, weight, LDM/volumetric/W&M, ADR compliance, and UK duty estimation into one response. Accepts multiple items with a transport mode (road/air/sea/multimodal). Returns per-mode calculations, DG compliance flags, and customs estimates.

Parameters (7)

modestringrequired
Transport mode
itemsarrayrequired
Array of shipment items with dimensions, weight, and optional HS/UN codes
originobject
Origin location — ISO country code and optional UN/LOCODE
destinationobject
Destination location — ISO country code and optional UN/LOCODE
incotermstring
Incoterms 2020 three-letter code (e.g. 'DAP', 'EXW', 'FOB')
freight_costnumber
Optional freight cost in GBP for duty calculation
insurance_costnumber
Optional insurance cost in GBP for duty calculation

uld_lookup

Look up air freight ULD (Unit Load Device) specs. 16 types including AKE (LD3), PMC, PLA, and special units. Returns dimensions, weights, volume, aircraft compatibility, and deck position.

Parameters (3)

typestring
ULD code (e.g., "AKE", "PMC") or slug (e.g., "ake-ld3"). Omit to list all.
categorystring
Filter by ULD category
deckstring
Filter by deck position

vehicle_lookup

Look up road freight vehicle and trailer specs. 17 types: curtainsiders, rigids, vans, US trailers. Returns internal dimensions, payload limits, pallet capacity, and features.

Parameters (3)

slugstring
Vehicle slug (e.g., "standard-curtainsider"). Omit to list all.
categorystring
Filter by category
regionstring
Filter by region

get_subscribe_link

Get the URL where the user can subscribe to FreightUtils Pro for higher API limits. Use this when the user asks how to upgrade, hits a rate limit, or asks about pricing. Returns the URL where the user can subscribe via web — agents must NOT attempt to complete the subscription themselves.

Parameters (1)

tierstring
Tier to surface (only "pro" supported today)

adr_lq_eq_check

Compare quantities against the ADR 2025 Limited Quantity (LQ, Chapter 3.4) and Excepted Quantity (EQ, Chapter 3.5, codes E1–E5) reference limits for one or more UN numbers. For each item it looks up the substance's LQ/EQ value and reports whether the entered quantity is within_limit, exceeds_limit, or not_permitted, with the limit and a plain-language reason; EQ mode also checks the per-outer total via inner_packaging_qty. Returns an overall_status (qualifies / partial / does_not_qualify) plus a per-item breakdown. This is a reference-data comparison against published LQ/EQ limits, not a certification that a shipment is compliant — use it to pre-screen small-quantity consignments before formal classification.

Parameters (2)

modestringrequired
Check mode: 'lq' (Limited Quantity, ADR 3.4) or 'eq' (Excepted Quantity, ADR 3.5)
itemsarrayrequired
Items to check (1–20 per call).

emissions_calculator

Estimate freight transport greenhouse-gas emissions (kgCO2e) for a shipment leg, per ISO 14083:2023 / GLEC Framework v3.2: emissions = mass × distance × a published emission-intensity factor (kgCO2e/tonne-km). Provide mass + distance_km + mode (road | rail | sea | air | inland_waterway); optionally choose sub_mode, region/authority (uk = DEFRA, us = EPA, fr = ADEME) and basis (wtw default, or ttw). Returns well-to-wheel AND tank-to-wheel emissions where the factor has both, the exact factor used (value, authority, edition), the tonne-km activity, and a _source citing BOTH the ISO method and the specific open factor. Use when an agent needs a carbon estimate for a known shipment whose mass and distance are already determined. Distinct from cbm_calculator / ldm_calculator / chargeable_weight_calculator (those size or bill a shipment; this one estimates its CO2e). Distance must be provided — this tool does NOT route, geocode, or compute distances. Best-effort reference estimate from open factors (DEFRA / EPA / ADEME) — NOT a verified or audited carbon report. IMPORTANT: pass ACTUAL GROSS MASS, not chargeable/volumetric weight (a common air-freight mistake — see mass_basis). The fleet-average factor already includes average empty running (see empty_running) — do NOT add your own empty-return leg. Sea and air are low-representativeness generic defaults: real emissions vary materially by vessel/aircraft type, load factor and routing (see representativeness + the result summary). An unknown mode/sub_mode/region returns available:false with the covered options, never a fabricated factor.

Parameters (7)

massnumberrequired
Shipment mass, expressed in mass_unit. Example: 1000
mass_unitstring
Unit for mass (default: kg)
distance_kmnumberrequired
Transport distance in kilometres — you provide it; the tool does not route or compute distance
modestringrequired
Transport mode
sub_modestring
Optional sub-mode / vehicle class (e.g. "articulated", "container ship", "long-haul"). Omit for the representative default; an unknown value returns available:false with the covered list.
regionstring
Factor source/region: uk = DEFRA, us = EPA, fr = ADEME. Default is per-mode.
basisstring
Emissions basis: wtw = well-to-wheel incl. upstream energy (default), ttw = tank-to-wheel / operation only

validate

Validate and parse freight identifiers by their public check-digit algorithms: shipping container numbers (ISO 6346), air waybill (AWB) numbers (IATA modulus-7) and IMO ship identification numbers. Two modes: pass text=<arbitrary string> to find and validate every identifier in it (e.g. a booking email line), OR pass value=<identifier>&type=<container|awb|imo> to validate one. Returns, per identifier found: type, the normalised form, valid (check-digit pass/fail), the expected vs actual check digit, and details (container → owner prefix + equipment category; AWB → airline prefix + the airline, resolved from the AWB-prefix dataset; IMO → the 7-digit number). Use when an agent needs to confirm a container/AWB/IMO number is well-formed, or to extract identifiers from a freeform string. STRUCTURAL ONLY — a valid check digit means well-formed, NOT that the container/shipment/vessel exists or is active; this is not a registry/tracking lookup. Distinct from container_lookup (that returns container TYPE dimensions/specs) and airline_lookup (that searches airlines); this checks an identifier's check digit and, for an AWB, names the operating airline.

Parameters (3)

textstring
Arbitrary string to scan for container / AWB / IMO identifiers (parse mode). Provide this OR value+type.
valuestring
A single identifier to validate (typed mode). Requires type.
typestring
Identifier type for value: container = ISO 6346, awb = IATA Air Waybill, imo = IMO ship number.

ics2_check

Check a goods description against the official EU ICS2 stop-words list — terms the European Commission deems too vague/generic to be accepted in an entry summary declaration (ENS) goods-description field (data element 18 05 000 000). Pass description=<goods description>; returns the flagged terms (each with a note on whether it is the standalone description = automatic rejection, or embedded = make the description more specific), a clean boolean, a caveat, and a _source citing the EU list + legal basis. Use to QA a goods description BEFORE filing an ENS — for customs/documentation teams, brokers, forwarders' documentation side, and agents building ENS/filing pipelines. STRICTLY a reference check: NOT an ENS filing, NOT a customs-compliance determination, NOT legal advice. The list is non-exhaustive and updated periodically; clean does NOT guarantee acceptance (the description must still be specific enough to identify the goods). No binary accepted/rejected verdict is returned. Distinct from hs_code_lookup (commodity codes) and uk_duty_calculator (duty/VAT).

Parameters (1)

descriptionstringrequired
The goods description to check against the EU ICS2 stop-words list.

README.md17 KBView on GitHub

FreightUtils MCP Server

The neutral freight reference layer for AI agents.

FreightUtils is the neutral freight reference layer for AI agents — authoritative dangerous-goods, customs, location and freight-calculation data an agent can call and cite, from primary sources (ADR 2025 / UNECE, HS 2022 / WCO, IATA-regulated airline prefixes). Neutral by design: no freight to sell and no carrier to push, so an agent can trust it as ground truth regardless of who carries the load.

This Model Context Protocol server gives AI agents access to 24 freight calculation and reference tools, covering road, air, and sea freight. Built by a UK ADR-certified freight transport planner.

Every response cites its source — a _source block with the authority, edition, licence and last-verified date — and the tools are deterministic, not generated answers. Reference only: never filing, booking, or legal advice, and results state when human review is required (validate is structural check-digit validation only; a clean ics2_check is not ENS acceptance; emissions figures are estimates, not audited reports).

Website: https://www.freightutils.com API Docs: https://www.freightutils.com/api-docs

Tools (24)

Calculators

Tool	Description
`ldm_calculator`	Loading metres for European and US road trailers
`cbm_calculator`	Cubic metres for sea freight
`chargeable_weight_calculator`	Air freight chargeable weight (volumetric vs actual)
`pallet_fitting_calculator`	Box-on-pallet optimisation with rotation
`container_lookup`	ISO container specs (10 types) and loading calculation
`unit_converter`	Weight, volume, length, and freight-specific conversions
`consignment_calculator`	Multi-item CBM, LDM, volumetric & mode-specific chargeable weight (sea/air/road) + advisory flags
`emissions_calculator`	Freight CO2e via the ISO 14083 / GLEC distance-based method — open DEFRA/EPA/ADEME factors (WTW + TTW); use actual gross mass (not chargeable/volumetric); result carries empty_running + representativeness (sea/air = low) + a summary

Dangerous Goods (ADR)

Tool	Description
`adr_lookup`	2,939 UNECE ADR 2025 entries
`adr_exemption_calculator`	ADR 1.1.3.6 small load exemption check
`adr_lq_eq_check`	Limited and Excepted Quantity eligibility

Customs & Tariff

Tool	Description
`hs_code_lookup`	6,940 Harmonized System tariff codes (HS 2022)
`uk_duty_calculator`	UK import duty and VAT (live GOV.UK Trade Tariff data)
`incoterms_lookup`	Incoterms 2020 — all 11 rules with risk/cost transfer points
`ics2_check`	Flag EU ICS2 unacceptable goods-description terms (stop-words) before filing an ENS — reference only

Reference Data

Tool	Description
`airline_lookup`	6,352 airlines with IATA/ICAO codes and AWB prefixes
`unlocode_lookup`	116,129+ UN/LOCODE transport locations
`airport_lookup`	85,555 airports by IATA/ICAO code, name or city (OurAirports)
`nearest_airport`	Nearest airports to a latitude/longitude, by great-circle distance
`uld_lookup`	16 air cargo ULD types (LD3, PMC, etc.)
`vehicle_lookup`	17 road freight vehicles and trailers

Validation

Tool	Description
`validate`	Parse any text (a booking line, an email) to find & validate every container (ISO 6346), AWB (modulus-7) and IMO number in it — or validate a single identifier by type

Composite

Tool	Description
`shipment_summary`	Chains CBM + weight + LDM + ADR + duty in one call

Subscription

Tool	Description
`get_subscribe_link`	URL to upgrade to FreightUtils Pro (50,000/month at £19/mo)

Installation

Claude Desktop / Claude Code (stdio)

Add to your MCP config (claude_desktop_config.json or .claude/settings.json):

json

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

Remote HTTP / SSE

If your MCP client supports remote servers, use the canonical URL:

code

https://www.freightutils.com/api/mcp

The older URL https://www.freightutils.com/api/mcp/mcp still works for backwards compatibility with existing clients.

No API key required to get started — anonymous calls work out of the box (see Rate Limits below).

Authenticating with a Pro key

Anonymous usage caps at 25 requests/day per IP. If you have a free or Pro API key, set FREIGHTUTILS_API_KEY in the environment that runs the MCP server. The package reads it from process.env and attaches Authorization: Bearer <key> to every outbound /api/* call — same key the remote https://www.freightutils.com/api/mcp transport already honors.

stdio config example with the env var wired through:

json

{
  "mcpServers": {
    "freightutils": {
      "command": "npx",
      "args": ["freightutils-mcp"],
      "env": {
        "FREIGHTUTILS_API_KEY": "fu_pk_xxx"
      }
    }
  }
}

Get a key at freightutils.com/api-docs (free, 100/day) or freightutils.com/pricing (Pro, 50,000/month). Backwards compatible — unset env var preserves the existing anonymous behaviour.

Verify your setup

After adding FreightUtils to your MCP client config, fully quit and relaunch the client (Claude Desktop, Cursor, Cline). MCP servers are only loaded at client startup; editing the config in a running session does nothing until restart.

Then run the install diagnostic from a terminal:

npx freightutils-mcp ping

You should see three ticks and All checks passed:

code

FreightUtils MCP Diagnostic
───────────────────────────
package: freightutils-mcp@2.10.0
health:  https://www.freightutils.com/api/mcp/health

[1/3] Backend health (https://www.freightutils.com/api/mcp/health)
      ✓ status=ok mcp_version=2.10.0 tools_registered=24 (143ms)

[2/3] MCP handshake (in-process via InMemoryTransport)
      ✓ server freightutils-mcp@2.10.0 initialized; tools/list returned 24 tools

[3/3] End-to-end tool call (cbm_calculator l=120 w=80 h=100)
      ✓ cbm_calculator → total=0.96 m³ (expected 0.96) (218ms)

All checks passed. Your FreightUtils MCP install is working.

If any check shows ✗, see Troubleshooting below. Exit code is 0 on all-pass and 1 on any failure, so the command works in CI / health-check scripts too.

Troubleshooting

Symptom	Likely cause	Fix
Tools not appearing in the MCP client after editing the config	Client wasn't fully restarted	Quit and relaunch (Cmd+Q on macOS / right-click → Quit on Windows tray). Closing the window is not enough.
`npx freightutils-mcp ping` check 1 fails with a network error	DNS, proxy, or the website is unreachable from your network	Check the status page at https://www.freightutils.com/status. If you're behind a corporate proxy, set `HTTPS_PROXY`. Override the host for `ping` with `FREIGHTUTILS_API_URL=<base-url>`.
`npx freightutils-mcp ping` check 2 fails	Broken local install (npx cache or stale Node version)	Re-install: `rm -rf ~/.npm/_npx && npm install -g freightutils-mcp` and rerun. Requires Node 18 or newer.
Tool calls return HTTP 429 / `"rate_limited"`	Anonymous IP cap of 25 requests/day exceeded	If you have a FreightUtils Pro API key, set `FREIGHTUTILS_API_KEY` in your environment before invoking the MCP. The package passes it through automatically on every outbound call. See https://www.freightutils.com/pricing if you need a key.
`"Server failed to start"` / spawn error in client logs	`npx` not on PATH, or Node older than 18	Install Node 18+. On macOS, an absolute path in the config (`"command": "/opt/homebrew/bin/npx"`) avoids PATH issues for GUI-launched clients.
Specific tool returns `isError: true`	Bad input shape, or an unknown lookup key (UN number / HS code / AWB prefix not in the dataset)	The tool's error body names the offending field. Verify against the schema at https://www.freightutils.com/api-docs or call the corresponding playground endpoint to confirm the input shape.

The full diagnostic flow lives at the /api-docs#mcp-setup section on the website. The live backend status is callable from inside any MCP client at GET /api/mcp/health — useful when you don't have shell access during a conversation.

Rate Limits

All tools call the free FreightUtils API:

Anonymous: 25 requests/day per IP
Free API key: 100 requests/day (register at https://www.freightutils.com)
Pro: 50,000 requests/month at £19/month

Example Prompts

Once connected, your AI agent can:

"Calculate CBM for a box 120cm × 80cm × 100cm, 24 pieces"
"Look up UN 1203 in the ADR database"
"Check if 200L of petrol qualifies for ADR 1.1.3.6 exemption"
"Find the HS code for lithium batteries"
"What does FOB mean in shipping?"
"How many boxes of 40×30×25cm fit on a euro pallet?"
"Calculate loading metres for 26 euro pallets on an artic trailer"
"What's the UK import duty on laptops from China?"

Data Sources

ADR 2025 — UNECE (licensed from Labeline.com)
HS 2022 — UN Comtrade (PDDL)
Airlines — public IATA/ICAO data, cross-referenced
UN/LOCODE — UNECE
UK Duty — live GOV.UK Trade Tariff API
Containers/ULD/Vehicles — ISO, IATA, and industry-standard specifications

Changelog

Full release notes also on GitHub Releases.

2.4.0 — 2026-06-16

consignment_calculator → canonical consignment v1. New transport mode (sea | air | road) and a canonical lines[] shape (each line: quantity, dims {l,w,h,unit} mm/cm/m/in, weight {value,unit} kg/g/t/lb, optional description/hs_code/un_number/stackable), plus an options object (air_volumetric_divisor default 6000, container_number, awb_number). The legacy flat items[] array (cm/kg) still works unchanged. Output gains per-line + grand totals, a schema_version, and advisory-only flags (implausible density, mode/option mismatch, dangerous-goods presence by UN number vs the ADR 2025 reference, ISO 6346 / IATA AWB check-digit) plus a best-effort disclaimer. Canonical schema: https://www.freightutils.com/schema/consignment.v1.json. No tool-count change (19).

2.1.1 — 2026-05-09

Fix: serverInfo.version was stuck at 1.0.8 even after 1.1.0 / 2.0.0 / 2.1.0 published. The wire-level identity has been silently lying about the package version since the 1.0.7 fix. Now reads from package.json at runtime via createRequire, so the wire version always matches the npm-published release.
Fix: server.json description undercounted tools ("18 freight tools …" → "19 freight tools …, get_subscribe_link").
Tightened Zod input constraints across airline_lookup, adr_lookup, adr_exemption_calculator, adr_lq_eq_check, unlocode_lookup, and uk_duty_calculator (regex / length / min-max on UN numbers, IATA / ICAO / AWB prefixes, ISO country codes, UN/LOCODE format). Field-level constraints take effect at the wire; .strict() on top-level schemas becomes wire-effective once the server.registerTool() migration ships in 2.2.0.

2.1.0 — 2026-05-01

New tool: get_subscribe_link. Returns the FreightUtils /pricing URL plus tier / monthly limit / monthly price metadata. Tool description tells agents NOT to attempt checkout themselves — they hand the URL to the user. Tool count: 18 → 19.
Pairs with the website-side fix wiring /api/mcp/* through the existing API rate-limit middleware so Pro keys are attributed against the 50,000/month bucket on MCP traffic.

2.0.0 — 2026-04-25 (BREAKING — input-side casing)

Tool input schemas migrated camelCase → snake_case to match the response convention shipped in 1.1.0. 13 input keys renamed across uk_duty_calculator, consignment_calculator, and shipment_summary (e.g. commodityCode → commodity_code, originCountry → origin_country, items[].grossWeight → items[].gross_weight). Agents calling these tools with prior camelCase keys now get a Zod validation error instead of a 200. Re-prompt or update tool-call code.
All other tools (cbm_calculator, chargeable_weight_calculator, ldm_calculator, pallet_fitting_calculator, unit_converter, ADR family, airline_lookup, container_lookup, hs_code_lookup, incoterms_lookup, unlocode_lookup, uld_lookup, vehicle_lookup) already used snake_case (or single-word) input keys and are unchanged.

1.1.0 — 2026-04-25 (BREAKING — response-side casing)

API responses migrated camelCase → snake_case site-wide across /api/unlocode, /api/uld, /api/containers, /api/vehicles, /api/consignment, /api/duty. All MCP tools in this package are passthroughs, so AI agents see snake_case keys (e.g. commodity_code, location_code, internal_length_cm) instead of the prior camelCase forms. Re-prompt or update parsing logic.
No code changes to MCP tool implementations — every tool was already a passthrough wrapper around apiGet / apiPost. Input schemas continue to declare camelCase here; 2.0.0 deliberately closes that asymmetry.
README badges: added monthly + total npm downloads alongside the existing version + license + Glama score badges.

1.0.8 — 2026-04-23 (hotfix)

Critical fix: revert list_prompts / list_resources stub handlers introduced in 1.0.7. The raw SDK asserts the corresponding capability must be declared before setRequestHandler is called — 1.0.7 threw Server does not support prompts at startup, crashing the MCP server on every run. 1.0.8 removes the stubs and restores boot.
Server identity bumped: version: '1.0.7' → '1.0.8'.
No other changes. 18 tools, annotations, shipment_summary descriptions, and smithery.yaml from 1.0.7 are preserved.

1.0.7 — 2026-04-22

Add smithery.yaml with empty configSchema (Smithery Quality Score: config UX +25).
Add read-only annotations to all 18 tools (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false) with human-readable title (+7).
Add missing parameter .describe(...) text to shipment_summary (+1).
Add stub list_prompts / list_resources handlers so probes return { prompts: [] } / { resources: [] } instead of -32601 Method not found (+5).
Fix server identity: name: 'FreightUtils' → 'freightutils-mcp', version: '1.0.0' → '1.0.7'.
No breaking changes. Same 18 tools, same names, same behaviour.

1.0.6 — 2026-04-22

Security: bump @modelcontextprotocol/sdk to 1.26.0 to patch CVE-2026-25536 (cross-client data leak via shared transport/server instance reuse). See GHSA-345p-7cg4-v4c7.
No user-facing API changes. Same 18 tools.

Other ways to use FreightUtils

FreightUtils ships across multiple distribution surfaces. Pick the one that fits how you work:

Website — interactive tools at freightutils.com
REST API — 23 endpoints, free tier (100/day) and Pro tier (50K/month, £19/mo). API docs
MCP server — for LLM agents and AI tooling. npm: freightutils-mcp · MCP Registry
n8n custom node — for workflow automation. npm: n8n-nodes-freightutils
Custom GPT — the FreightUtils GPT on the OpenAI GPT Store, backed by the same OpenAPI spec.

Same data, same compliance reference set (ADR 2025, HS 2022, IATA-regulated airline prefixes), every surface kept in sync.

License

MIT — see LICENSE.

Built by Marius Cristoiu, ADR-certified freight transport planner.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "freightutils": {
      "command": "npx",
      "args": [
        "-y",
        "freightutils-mcp@2.10.1"
      ]
    }
  }
}