FreightUtils MCP Server is a neutral freight reference layer for AI agents, built by Marius Cristoiu, a UK ADR-certified dangerous goods transport planner. It provides traceable, citable data on dangerous goods, customs, locations, and freight calculations, sourced from primary sources (ADR 2025 / UNECE, HS 2022 / WCO, IATA-regulated airline prefixes). It is neutral by design: it does not sell freight and does not promote carriers—queries return the content of the specified source with citations, so agents can check it themselves rather than relying solely on its claims.
Purpose This Model Context Protocol server provides AI agents with 25 freight calculation and reference tools covering road, air, and sea freight. Every response cites its source—a _source block containing the authority, version, license held (if any), and verification status that the agent can read. The tools are deterministic, not generated answers. Reference only: it never files declarations, makes bookings, or provides legal advice, and results state when human review is required (validate is only a structural check-digit verification; a clean ics2_check does not mean an ENS has been accepted; emissions data are estimates, not audit reports).
Key capabilities As of 2.11.0, every tool also declares a typed outputSchema and returns structuredContent—the FreightUtils v1 response envelope: results under result, plus confidence, normalized_input, warnings, _source, and a ready-to-use citation. The legacy flat JSON text channel remains unchanged (byte-for-byte identical), so existing text-parsing consumers are unaffected.
Dangerous goods (ADR): Some UN numbers have multiple rows in ADR Table A (packing group, concentration bands). When a bare UN number matches rows that give different answers, the ADR tools do not choose on their own: they withhold the ruling and return the candidate rows, and the user must specify one via packing_group or variant_index. The relevant rules and examples (UN 1789, UN 1790 PG I, UN 2215 PG III) are in the ADR 1.1.3.6 calculator in the API documentation.
Customs and tariffs: Provides HS code lookup, tariff estimation, and more.
How to use Claude (claude.ai, desktop and mobile apps, Cowork): Add FreightUtils from Claude's connector directory:and more.
How to use Claude (claude.ai, desktop and mobile apps, Cowork): Add FreightUtils from Claude's connector directory:https://claude.ai/directory/connectors/freightutils。或作为自定义连接器添加——Customize → Connectors → Add custom connector—the URL is https://www.freightutils.com/api/mcp。无需 API key, no login required. Setup, limits, and privacy: freightutils.com/mcp#use-in-claude.
Claude Desktop / Claude Code (stdio): Add to the MCP configuration (claude_desktop_config.json or .claude/settings.json).
Remote HTTP / SSE: If the MCP client supports remote servers, use the canonical URL. The legacy URL https://www.freightutils.com/api/mcp/mcp remains backward compatible. No API key is needed to get started—anonymous calls work out of the box.
Authenticating with a Pro key: Anonymous use is limited to 25 requests per IP per day. If you have a free or Pro API key, set FREIGHTUTILS_API_KEY in the environment where the MCP server runs. The package reads it from process.env and attaches Authorization: Bearer <key> to every outbound /api/* call—remote https://www.freightutils.com/api/mcp Transmission already supports the same key. Key acquisition: freightutils.com/api-docs (free, 100/day) or freightutils.com/pricing (Pro, 50,000/month). Backward compatible—if the environment variable is not set, existing anonymous behavior is maintained. When no key is set, the server explains this once at startup via stderr (stdout carries only the MCP protocol), so that a missed key appears in the client MCP logs rather than at the first 429.
Verify setup: after adding FreightUtils to the MCP client configuration, fully quit and restart the client (Claude Desktop, Cursor, Cline). The MCP server is loaded only when the client starts; editing the configuration during a running session has no effect until restart. Then run the installation diagnostic from the terminal. You should see three checkmarks and All checks passed. If any check shows ✗, see troubleshooting. The exit code is 0 if all pass and 1 if any fail, so this command can also be used in CI / health check scripts.
Troubleshooting: for the full diagnostic procedure, see the /api-docs#mcp-setup section of the website. Live backend status can be called from within any MCP client via GET /api/mcp/health—useful when there is no shell access in the conversation.
Applicable scenarios All tool calls are free with the FreightUtils API: anonymous 25 requests per IP per day; free API key 100 per day (at https://www.freightutils.com sign up); Pro 50,000 requests per month, £19/month.
Example prompts: once connected, the AI agent can: calculate the CBM of 24 boxes of 120cm × 80cm × 100cm; look up UN 1203 in the ADR database; check whether 200L of petrol qualifies for the ADR 1.1.3.6 exemption; find the HS code for lithium batteries; what FOB means in shipping; how many boxes of 40×30×25cm fit on a Euro pallet; calculate the loading meters of 26 Euro pallets on an articulated truck; what the UK import tariff is for importing laptops from China.
Security and data Read-only. Every tool is a query or calculation, declaring readOnlyHint: true and destructiveHint: false. The server changes nothing anywhere. No filesystem, no shell. The server reads no files other than its own package.json, starts no processes, and opens no ports—it communicates only via stdio. Single destination. Tool inputs are sent only to https://www.freightutils.com/api（或 FREIGHTUTILS_API_URL), over HTTPS. get_subscribe_link responds 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 placed in error messages. stdout is the protocol. Nothing but MCP JSON-RPC enters stdout; the only startup notification goes to stderr. Two layers of validation. Each tool's Zod schema checks types, formats, and the API's own limits before invocation (the three ADR tools—adr_exemption_calculator, adr_lq_eq_check, shipment_summary—also reject by name fields they do not read). The API then validates every request again on the server and rejects unanswerable requests with a 400 naming the field. Errors keep their meaning. Failed calls are reported by type: network failure, timeout (30 seconds, or FREIGHTUTILS_TIMEOUT_MS), the API's own 4xx rejection, 429 with reset_at, or 5xx—never with stack traces, request headers, or server error page content. Two direct runtime dependencies: @modelcontextprotocol/sdk and zod. CI fails on any high or critical advisory in the production dependency tree, monitored by Dependabot. To report a vulnerability: see SECURITY.md.
Data sources ADR 2025—UNECE, ECE/TRANS/352, applicable from 1 January 2025; given legal effect by EU Directive 2008/68/EC (consolidated). A compilation of facts, best effort—not legal advice, not a regulator. HS 2022—HS 2022 descriptions from UN Comtrade's H6 classification (UN Statistics Division); WCO maintains the Harmonized System nomenclature. No designated open license. Airlines—compiled by FreightUtils from public sources. Verified records cite the carrier's published page 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 ICAOand no license or "open data" claim is made for it. UN/LOCODE 2025-1—the official UNECE release artifact, with coordinates strictly verified. UN/LOCODE © UNECE, CC BY 4.0 (as UNECE states for UN/CEFACT standards). UK Tariff—the live GOV.UK Trade Tariff API, pulled on request, so no local copy can drift. Containers / ULDs / vehicles—ISO, IATA, and industry standard specifications. Emission factors—published DEFRA / EPA / ADEME factors (currently DEFRA 2026 + EPA 2025 ADEME Base Carbone v23.11), combined using the ISO 14083 / GLEC distance method. Estimates, not audit reports. Public-source wording is maintained in docs/DATA_PROVENANCE.md in the FreightUtils repository and copied here, rather than written from memory—so a source reattributed there cannot continue to be cited here.
Other ways to use it FreightUtils is published across multiple distribution channels. Choose the one that fits how you work: Website—interactive tools at freightutils.com; REST API—24 endpoints, free tier (100/day) and Pro tier (50K/month, £19/month), API documentation; MCP server—for LLM agents and AI tools, 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 specification. Same data, same compliance reference set (ADR 2025, HS 2022, IATA-regulated airline prefixes), with every channel kept in sync.
Limitations For reference only; no filing, booking, or legal advice is provided. Results state when human review is required. validate is only a structural check-digit verification; a clean ics2_check does not mean an ENS is accepted; emissions data are estimates, not audit reports. Anonymous use is capped at 25 requests per IP per day. License: MIT—see LICENSE。
