Repository avatar
AI Tools
v2.34.4
active

freightutils

io.github.SoapyRED/freightutils

Neutral freight reference + validation layer for AI agents: ADR, HS, UN/LOCODE, freight math

Documentation

FreightUtils MCP Server

npm version npm downloads (total) npm downloads (month) License: MIT FreightUtils MCP server

The neutral freight reference layer for AI agents.

FreightUtils is the neutral freight reference layer for AI agents — source-backed 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 — a lookup returns what the named source says, with the citation attached so an agent can inspect it rather than take our word for it, regardless of who carries the load.

This Model Context Protocol server gives AI agents access to 26 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 where held, and a verification status an agent can read — 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).

Since 2.11.0, every tool also declares a typed outputSchema and returns structuredContent — the FreightUtils v1 response envelope: the answer under result, plus confidence, normalized_input, warnings, _source and a ready-to-use citation. The legacy flat JSON text channel is unchanged (byte-identical), so existing text-parsing consumers are unaffected.

Since 2.24.0 the envelope is version 1.2, which adds four fields beside ok: status (ok, partial when required inputs are missing, not_found, ambiguous or unsupported), missing_inputs (the inputs a partial answer still needs), edition (the edition the answer is served from, with the dates it applies from and may apply until; null for a computed or live answer) and as_of (the date the answer's data was last audited, or today for a computed answer). A refusal carries the same envelope on structuredContent, so an agent can read partial and missing_inputs there as well. The change is additive: envelope 1 and 1.1 answers still validate.

Since 2.26.0:

  • ADR 2025 and ADR 2027. The tools that read ADR data — adr_lookup, adr_exemption_calculator, adr_lq_eq_check, consignment_calculator, shipment_summary and, from 2.29.0, adr_consignment_check — take edition ("2025" or "2027") and as_of (YYYY-MM-DD). edition wins; otherwise as_of (default today, UTC) picks the edition by the legal timeline. Without either, they answer ADR 2025 until 31 December 2026 and ADR 2027 from 1 January 2027. ADR 2027 is accepted and applies from 1 January 2027: an ADR 2027 answer for an earlier date says it is not yet applicable on that as_of (EDITION_NOT_YET_APPLICABLE). From 1 January to 30 June 2027 either edition may be applied (EDITION_TRANSITIONAL); ADR 2025 answers end on 30 June 2027, and from 1 July 2027 edition: "2025" is refused with EDITION_UNSUPPORTED. An answer on a named edition carries adr_edition; an ADR 2027 exemption answer for UN 0081, 0082, 0084, 0241, 0331, 0332, 0482, 1005 or 1017 also carries transitional_1_6_1_61 (the ADR 2025 note-a basis that 1.6.1.61 allows until 31 December 2030) beside the verdict, never instead of it.

Since 2.25.0:

  • The ADR consignment check (2.29.0). adr_consignment_check takes the consignment object (lines[] with un_number, quantity { value, unit, basis }, packing_group / variant_index, packages, inner_packaging and, on an ID line, icao_limited_quantity; journey { date, tunnels_on_route, mode }) with edition / as_of beside it (journey.date is the default as_of) and answers status — pass, fail, conditional or insufficient_data — with missing_inputs[] (each input by path, the check it blocks, what to send) and checks_performed[] (each check's verdict, edition, date, basis and the ADR section and page it rests on). The 1.1.3.6 check is adr_exemption_calculator's answer, whole; the LQ / EQ checks are adr_lq_eq_check's; the tunnel check gives the whole load's code (the most restrictive, 8.6.3.2) and which tunnels on the route the load may use without and with the 1.1.3.6 relief (8.6.3.3); the document entries follow 5.4.1.1.1 (a), (b), (c), (d), (k), e.g. UN 1098 ALLYL ALCOHOL, 6.1 (3), I, (C/D). From 2.30.0 it also checks mixed loading (mixed_loading_7_5_2): every pair of lines against the ADR 7.5.2.1 table by the labels of Table A column (5), subsidiary labels included, Class 1 pairs against the 7.5.2.2 table by compatibility group, each pair with its deciding cell (e.g. 3 × 1.4) and source; and the foodstuffs precautions of 7.5.4 for goods with CV28, with the optional vehicle.foodstuffs_carried. Where the ADR text does not settle a case the check asks instead of assuming. From 2.31.0 it also checks the vehicle side — plates and placards (5.3), vehicle equipment (8.1) and driver training (8.2) — and from 2.32.0 the UN packaging mark of each line (6.1.3.1); the packaging kind against the packing instruction is not checked. A keyed call stores a check receipt.
  • Check receipts. A receipt is stored only when the package runs with an API key (FREIGHTUTILS_API_KEY) — a free key is enough (freightutils.com/pricing). Then every answer of the seven executed checks (adr_exemption_calculator, adr_lq_eq_check, uk_duty_calculator, consignment_calculator, shipment_summary, ics2_check and, from 2.29.0, adr_consignment_check) carries _meta.check_id and _meta.receipt_url. A receipt is the record of that one check, kept for 90 days at GET https://www.freightutils.com/api/receipts/{check_id} (?format=text for a summary): the inputs as consumed, the edition and as-of date, the data hashes, the rules applied, the result, anything unresolved and a receipt_hash a copy can be checked against. Without a key the answer carries the receipt hash inline and nothing is stored: _meta.receipt (stored: false, reason: "key_required"; from 2.28.0 the reason may also be "quota" — the key's daily stored-receipt allowance for the day is used up, the answer is unchanged and nothing is stored; receipt_hash and the hashed fields the answer does not otherwise carry, so the hash recomputes from the answer alone), and no check_id (the API's rule since 30 October 2026, typed in this package from 2.26.0). Verifying by id needs no plan and no payment — a keyed check's receipt is read with the same key — and a fetch counts as one request against the daily allowance, like a lookup. A receipt never holds a name, an address, a key or an IP address. Every check also names the edition it rested on (edition + as_of), or answers edition: null with _meta.edition_basis "no regulatory dataset read".
  • Batch inputs. adr_lookup takes un_numbers[]; unlocode_lookup, airport_lookup, airline_lookup and hs_code_lookup take codes[] (up to 50 each); uk_duty_calculator takes lines[] (up to 10). Send the list alone: the answer is results[] in input order, each item with its own status. One call against the daily limit, one per item against the Pro monthly allowance.
  • What each ADR code means. adr_lookup answers resolved_codes[] beside results[]: each code in Table A columns (5)–(20), once per answer, with the rows that carry it, its summary, ADR section and verification_status. include_codes picks compact (the default for a UN number), full (adds the url, title, meaning and references) or none; include_statements: true adds plain-word statements to every row. The meanings are FreightUtils' paraphrases of ADR 2025, cited to section, and verification_status says how each has been reviewed: paraphrase_unreviewed, machine_reviewed (two independent readings of the UNECE text, compared with the record; the owner adjudicates every disagreement), contested, owner_reviewed, dg_reviewed, needs_fix, or verified on the transport category and tunnel code entries read from the 1.1.3.6.3 and 8.6.4 tables (typed from 2.28.0).
  • Scopes. --scope dg | customs | ops (or FREIGHTUTILS_SCOPE) serves only that scope's tools — see Scoped tool lists. The default serves all of them.
  • The consignment object. consignment_calculator, shipment_summary and adr_exemption_calculator take one consignment argument (schema) instead of their own inputs; validate checks one with type: "consignment".

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

Rules every tool shares

Since 2.34.3 these are said once — here and in the server's instructions (sent on initialize) — instead of in each tool's description, so the tool list is lighter (about 57,400 tokens for all 26 tools, 14,700 of them to choose and call, against 79,400 and 31,600 in 2.34.2):

  • structuredContent is the FreightUtils response envelope: the answer under result, plus confidence, _source and citation.
  • Field names as this package serves them (snake_case); the hosted /api/mcp endpoint serves the same fields in camelCase (e.g. total_cbm → totalCbm).
  • Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.
  • 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.
  • ADR 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.
  • Identifiers: each record carries fu_id, a stable FreightUtils identifier (and fu_version_id where the dataset has editions); resolve_reference resolves one to exactly its record.
  • Lists: a list (no single record asked for) returns summary rows with total, truncated, next_offset and detail_hint; full: true returns full records five per page, with offset / limit to page.
  • Batch arguments (codes, un_numbers, lines): send alone; answered as results[] in input order, each with its own status. One call against the daily limit, N against the Pro monthly allowance.
  • consignment: the consignment object may replace a tool's other arguments; send it alone; an input the tool needs and the object lacks comes back in missing_inputs.

Tools (26)

Calculators

ToolDescription
ldm_calculatorLoading metres for European and US road trailers
cbm_calculatorCubic metres for sea freight
chargeable_weight_calculatorAir freight chargeable weight (volumetric vs actual)
pallet_fitting_calculatorBox-on-pallet optimisation with rotation
container_lookupISO container specs (10 types) and loading calculation
unit_converterWeight, volume, length, and freight-specific conversions
consignment_calculatorMulti-item CBM, LDM, volumetric & mode-specific chargeable weight (sea/air/road) + advisory flags
emissions_calculatorFreight 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)

ToolDescription
adr_lookup2,939 UNECE ADR 2025 entries, all 20 Table A columns — beyond class, packing group, labels, special provisions, LQ/EQ, transport category, tunnel code and HIN: packing_instructions, special_packing_provisions, mixed_packing_provisions, portable_tank_instructions, portable_tank_special_provisions, tank_code, tank_special_provisions, vehicle_for_tank_carriage, carriage_packages, carriage_bulk, carriage_loading_unloading_handling, carriage_operation
adr_exemption_calculatorADR 1.1.3.6 small load exemption check
adr_lq_eq_checkLimited and Excepted Quantity eligibility
adr_consignment_checkOne call on the consignment object: the 1.1.3.6 verdict, LQ / EQ per line, the whole-load tunnel code against the route (ADR 8.6.3 / 8.6.4), the 5.4.1.1.1 transport-document entries and mixed loading (7.5.2, 7.5.4), with one status and page-cited checks

In 2.34.0: the envelope declares _meta.upstream — the upstream state of the datasets an answer was drawn from, as the site's daily upstream check recorded it: per dataset the state (in_step, changed_upstream, schema_drift, unreachable, window_missed, or unknown when it could not be read), how the dataset is watched, the last successful check and the window, with stale true only when a dataset missed its window (the answer is still the last verified edition held). Optional and passthrough, so an answer without it still validates. It says whether the upstream was checked inside its window, not that an answer is right (data status). Still 26 tools.

In 2.33.0: every record the fifteen record tools return declares fu_id (a stable FreightUtils identifier, the same across editions) and, where the dataset has editions, fu_version_id (fu_id@<edition>) — optional strings on passthrough records, so an answer without them still validates; the envelope declares _meta.ids { scheme, pattern }; each of those tools says so in one closing clause; and resolve_reference takes an fu: identifier of up to 200 characters, which resolves to exactly its one record or to none (every other identifier keeps the 32-character limit). Still 26 tools.

In 2.32.0: adr_consignment_check reads the UN packaging mark of each line — the optional lines[].packages.un_mark, read by ADR 6.1.3.1 field by field (symbol, the 6.1.2.7 code, the X / Y / Z packing-group letter and the density or gross mass, S or the test pressure, year, State, maker) and its letter held against the line's packing group (packaging_code_validity; no mark → conditional; the packaging kind against the packing instruction is not checked) — and leaves a limited / excepted quantity line whose stated regime is met out of the 1.1.3.6 total (ADR 1.1.3.6.5, exemption_1_1_3_6.engine.excluded_lines). Nothing removed: every 2.31.0 argument and answer field still validates.

In 2.31.0: adr_consignment_check answers the vehicle side — placards_and_plates_5_3 (orange-coloured plates, placards for Class 1 / Class 7 packages, the 5.3.6 mark, the 3.4.13 LQ mark as a condition), equipment_8_1 (documents, the 8.1.4.1 extinguisher band by the transport unit's mass, the 8.1.5 items by danger label) and driver_training_8_2 (the 8.2.1 certificate and Class 1 / Class 7 specialisations; 8.2.3 / Chapter 1.3 under 1.1.3.6). Each lists the requirements the load puts on the vehicle and checks them against the optional vehicle.* / crew inputs; without them a dangerous-goods load is conditional. fail means a check the load does not meet: a load outside 1.1.3.6 answers exemption_1_1_3_6: not_applicable (a fully regulated load, not a failed one), a line with no stated regime that fits neither LQ nor EQ is not_applicable, and result.regime ("1.1.3.6" | "full_adr" | "undetermined") says which rules the checks answered under.

In 2.30.0: adr_consignment_check checks mixed loading (mixed_loading_7_5_2: every pair of lines against the ADR 7.5.2.1 table by the labels of Table A column (5), Class 1 pairs against 7.5.2.2 by compatibility group, each pair with its deciding cell, e.g. 3 × 1.4, and source; the foodstuffs precautions of 7.5.4 for goods with CV28) and takes the optional vehicle.foodstuffs_carried. Still to come: plates and placards 5.3, equipment 8.1 and driver training 8.2.1 in build 2c, packaging codes in build 2d. Nothing removed: every 2.29.0 argument and answer field still validates.

In 2.29.0: adr_consignment_check (above; checks today: 1.1.3.6, LQ / EQ per line, the tunnel code, the transport-document entries; coming: mixed loading 7.5.2 in build 2b, plates and placards 5.3, equipment 8.1 and driver training 8.2 in build 2c, packaging codes in build 2d — each listed as not_in_this_version until then; a keyed call stores a check receipt, a keyless one carries the receipt hash). adr_exemption_calculator types two fields the API already serves: strict_adr_2027.entry_deleted (with deleted_un_numbers and message) and items[].edition_basis. A line whose entry is deleted in ADR 2027 (e.g. UN 2941) has no ADR 2027 figure; on a stated as_of from 2027-01-01 to 2027-06-30 the load is answered on ADR 2025 under 1.6.1.1 (basis: "1.6.1.1", every line edition_basis: "2025"), the strict block's four figures null. Nothing removed: every 2.28.0 argument and answer field still validates.

In 2.28.0: adr_exemption_calculator mirrors the website's 4 November calculator changes.

  • icao_limited_quantity (boolean, on an ID-prefixed line such as ID8000): an air-only line is counted out of 1.1.3.6 (AIR_ONLY_ID) only when the request states that the packages are limited quantities to the ICAO Technical Instructions; without it the line is BLOCKED (entry_required). On a UN-numbered line the API answers 400.
  • An item quantity of 0 is accepted: the goods are read as not carried, the line is left out of the load (state EXCLUDED_NIL) and named in a warning; a load of nothing but zeros is refused, never cleared.
  • A gross mass on an entry counted by mass is an upper bound of the net mass: the load is exempt on it only when it clears even so (figure_basis: "upper_bound_gross", items[].upper_bound_gross).
  • ADR 2027 answers carry basis (adr_2027, 1.6.1.61 or 1.6.1.1). ADR 2027 applies from 1 January 2027; on a stated as_of from that date, a transitional measure that clears a load ADR 2027 itself does not is headlined, with basis_until and the strict ADR 2027 figure beside it (strict_adr_2027); transitional_1_6_1_1 states the load on ADR 2025 inside the 1.6.1.1 window.

adr_lookup types verification_status as the ADR code registry serves it (see below). Nothing removed: every 2.27.0 argument and answer field still validates.

In 2.26.0: edition and as_of on the five ADR tools — ADR 2025 and ADR 2027 (accepted, applying from 1 January 2027) by edition or by date, with the ADR 2027 answer fields (adr_edition, transitional_1_6_1_61, transitional_notes, amended_in_2027); a check receipt is stored for keyed calls only, and an answer without a key carries its receipt hash in _meta.receipt. Nothing removed: every 2.25.0 argument and answer field still validates.

In 2.25.0: check receipts, batch inputs, resolved_codes on adr_lookup (what each Table A code means), --scope dg | customs | ops, the consignment object, and resolve_reference decodes ADR Table A codes ("TU9"). Nothing removed: every 2.24.0 call answers as before.

In 2.24.0: every tool answers with response envelope 1.2 (status, missing_inputs, edition, as_of); unlocode_lookup says 116,086 UN/LOCODE codes. In 2.23.0, adr_lookup gained the 12 further Table A columns (packing, tank, vehicle and carriage provisions, columns 8–14 and 16–19) in its description and result schema; empty columns are null.

Some UN numbers have more than one ADR Table A row (packing groups, concentration bands). When a bare UN number matches rows that give different answers, the ADR tools never pick one: they withhold the verdict and return the candidate rows, and you pin one with packing_group or variant_index. The rules, with worked cases (UN 1789, UN 1790 PG I, UN 2215 PG III): the ADR 1.1.3.6 calculator in the API docs.

Customs & Tariff

ToolDescription
hs_code_lookup6,936 Harmonized System codes (HS 2022): 96 chapters, 1,228 headings, 5,612 subheadings
uk_duty_calculatorUK import duty and VAT (live GOV.UK Trade Tariff data)
incoterms_lookupIncoterms 2020 — all 11 rules with risk/cost transfer points
ics2_checkFlag EU ICS2 unacceptable goods-description terms (stop-words) before filing an ENS — reference only

Reference Data

ToolDescription
resolve_referenceResolve any freight identifier ("176", "UN1845", "NLRTM", "FOB") to typed, ranked, cited candidates when its type is unknown
airline_lookup6,356 airlines with IATA/ICAO codes and AWB prefixes
unlocode_lookup116,086 UN/LOCODE transport locations
airport_lookup86,281 airports by IATA/ICAO code, name or city (OurAirports)
nearest_airportNearest airports to a latitude/longitude, by great-circle distance — by default airports with scheduled airline service and an IATA code (include_all: true lists every type)
uld_lookup16 air cargo ULD types (LD3, PMC, etc.)
vehicle_lookup17 road freight vehicles and trailers

What's new in 2.27.0: the airline record's operational status, shared-prefix flag and air-safety-list flags; nearest_airport's scheduled-service default with include_all; the refreshed airport fields; failure reasons on validate and resolve_reference. Nothing removed: every 2.26.0 argument and answer field still validates.

  • Airlines (airline_lookup). A cargo carrier's record carries operational_status (active, ceased or unknown) with operational_status_basis — the carrier's own published page, a current FAA designator listed for that carrier, or a dead-domain check after the FAA withdrew the designator. It is a separate thing from the verification status ladder: a record can be historical in verification and still say why the carrier is ceased. Every record with an AWB prefix carries prefix_shared and prefix_holders (prefix 081 is shared by four carriers, Qantas among them). restrictions[] lists the carrier when the EU Air Safety List or the UK Air Safety List names it, with the list, annex, regulation or list date and the source URL. It is a flag with its source, not a legal determination — best-effort; verify with the list itself. Where the carrier publishes them, the record links its own cargo website (cargo_website), its tracking URL template (tracking_url_template) and its dangerous-goods acceptance page (dg_acceptance_url).
  • Airports (airport_lookup, nearest_airport). 86,248 airports from the OurAirports refresh of 30 October 2026; records gain icao_code, scheduled_service, iso_region, gps_code and keywords. nearest_airport answers, by default, airports with scheduled airline service and an IATA code — never a heliport and never a closed field. include_all: true lists every type except closed fields; a type filter keeps the earlier behaviour for that type. Every answer states distance_basis: "great_circle", the filter applied (scheduled_iata, all or type) and filter_description. The hosted server changed the same way on 30 October; the package now sends include_all and types the answer.

Validation

ToolDescription
validateParse 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

Failure reasons (2.27.0). An invalid identifier in a validate answer carries failure — reason (INVALID_CHECK_DIGIT, WRONG_LENGTH or BAD_CHARSET), message, expected_format and an example of a valid one — so an agent can tell the user what to fix ("176-12345676": the check digit is 6, the modulus-7 calculation gives 5). An AWB whose prefix no record holds, or several records share, says so in details.airline_failure (UNKNOWN_PREFIX / AMBIGUOUS); the check digit is a different question. resolve_reference carries validation (type, valid, failure) when the query is an AWB, container or IMO number — an invalid AWB still names the carrier its prefix belongs to — and failure (NO_MATCH / AMBIGUOUS, with candidate_types) when nothing or more than one type matched.

Composite

ToolDescription
shipment_summaryChains CBM + weight + LDM + ADR + duty in one call

Plans

ToolDescription
get_subscribe_linkThe pricing page URL with the Pro plan's limit and price (50,000/month at £19/mo)

Installation

Claude (claude.ai, desktop and mobile apps, Cowork)

Add FreightUtils from Claude's connector directory: https://claude.ai/directory/connectors/freightutils. Or add it as a custom connector — Customize → Connectors → Add custom connector — with the URL https://www.freightutils.com/api/mcp. No API key, no sign-in. Setup, limits and privacy: freightutils.com/mcp#use-in-claude.

Claude Desktop / Claude Code (stdio)

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

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

Scoped tool lists

An agent that only does one job can load fewer tool definitions. --scope (or the FREIGHTUTILS_SCOPE environment variable) serves one scope — the same tools, names, schemas and answers, filtered:

ScopeTools
dgadr_lookup, adr_exemption_calculator, adr_lq_eq_check, adr_consignment_check, validate, resolve_reference
customshs_code_lookup, uk_duty_calculator, ics2_check, incoterms_lookup, validate
opsthe 11 calculators and equipment lookups, unlocode_lookup, airport_lookup, nearest_airport, airline_lookup, validate, resolve_reference (17)
all (default)every tool
{
  "mcpServers": {
    "freightutils-dg": {
      "command": "npx",
      "args": ["freightutils-mcp", "--scope", "dg"]
    }
  }
}

The hosted endpoint serves the same lists at https://www.freightutils.com/api/mcp/dg, /customs and /ops. An unknown scope stops the server with an error naming the four.

Remote HTTP / SSE

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

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:

{
  "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.

With no key set, the server says so once at start-up, on stderr (stdout carries only the MCP protocol), so a key you meant to set and missed shows up in your client's MCP log rather than at the first 429:

freightutils-mcp: FREIGHTUTILS_API_KEY is not set, so calls use the anonymous tier — 25 requests per day per IP address. Set the key to use your plan's limit: https://www.freightutils.com/pricing

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:

FreightUtils MCP Diagnostic
───────────────────────────
package: freightutils-mcp@<installed version>
health:  https://www.freightutils.com/api/mcp/health

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

[2/3] MCP handshake (in-process via InMemoryTransport)
      ✓ server freightutils-mcp@<installed version> initialized; tools/list returned <n> 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

SymptomLikely causeFix
Tools not appearing in the MCP client after editing the configClient wasn't fully restartedQuit 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 errorDNS, proxy, or the website is unreachable from your networkCheck 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 failsBroken 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 exceededIf 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 logsnpx not on PATH, or Node older than 18Install 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: trueBad 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

Security and data

  • Read-only. Every tool is a lookup or a calculation, declared readOnlyHint: true and destructiveHint: false. The server changes nothing, anywhere.
  • No file system, no shell. The server reads no file except its own package.json, starts no process and opens no port — it talks over stdio only.
  • One destination. Tool inputs go only to https://www.freightutils.com/api (or the base you set in FREIGHTUTILS_API_URL), over HTTPS. get_subscribe_link answers locally and sends nothing.
  • The key stays in the environment. FREIGHTUTILS_API_KEY is read from the environment and sent only as an Authorization: Bearer header to that host — never logged, never written to disk, never put in an error message.
  • stdout is the protocol. Nothing but MCP JSON-RPC goes to stdout; the one start-up notice goes to stderr.
  • Two validation layers. Each tool's Zod schema checks types, formats and the API's own limits before any call is made (the three ADR tools — adr_exemption_calculator, adr_lq_eq_check, shipment_summary — also refuse, by name, a field they do not read). The API then validates every request again on the server and refuses what it cannot answer with a 400 naming the field.
  • Errors keep their meaning. A failed call is reported by kind: network failure, timeout (30 s, or FREIGHTUTILS_TIMEOUT_MS), the API's own 4xx refusal, a 429 with its reset_at, or a 5xx — never with a stack trace, a request header or the contents of a server error page.
  • Two direct runtime dependencies: @modelcontextprotocol/sdk and zod. CI fails on any high or critical advisory in the production dependency tree, and Dependabot watches it.
  • Reporting a vulnerability: see SECURITY.md.

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, ECE/TRANS/352, applicable 1 Jan 2025; given legal effect by EU Directive 2008/68/EC (consolidated). Factual compilation, best-effort — not legal advice, not a regulatory authority.
  • HS 2022 — HS 2022 descriptions from UN Comtrade's H6 classification (UN Statistics Division); the WCO maintains the Harmonized System nomenclature. No named open licence.
  • Airlines — compiled by FreightUtils from public sources. Verified records cite carrier-published pages and FAA Order JO 7340.2 field by field; the rest are pending verification. IATA and ICAO assign these codes, but this dataset is not published or endorsed by IATA or ICAO, and no licence or "open data" claim is made for it.
  • UN/LOCODE 2025-1 — UNECE official release artifact, coordinates strict-validated. UN/LOCODE © UNECE, CC BY 4.0 (as UNECE states for UN/CEFACT standards).
  • UK duty — the live GOV.UK Trade Tariff API, pulled per request, so there is no local copy that can drift.
  • Containers / ULD / vehicles — ISO, IATA and industry-standard specifications.
  • Emissions factors — published DEFRA / EPA / ADEME factors (currently DEFRA 2026 + EPA 2025
    • ADEME Base Carbone v23.11), combined by the ISO 14083 / GLEC distance-based method. Estimates, not audited reports.

Public provenance wording is maintained in the FreightUtils repository's docs/DATA_PROVENANCE.md and copied here, not written from memory — so a source that is re-attributed there cannot keep being cited here.


Changelog

Release notes: CHANGELOG.md in this repo and GitHub Releases.

A README that carries its own copy of the changelog is why three directories showed 2.4.0 as the latest release for three months after 2.4.0 had been superseded. One source now.


Other ways to use FreightUtils

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

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.

NPM
freightutils-mcp
Install Command
npm install freightutils-mcp