{"id":49936354,"url":"https://github.com/soapyred/freightutils-mcp","last_synced_at":"2026-05-31T10:00:54.814Z","repository":{"id":351076006,"uuid":"1200163235","full_name":"SoapyRED/freightutils-mcp","owner":"SoapyRED","description":"FreightUtils MCP Server — 18 free freight tools for AI agents","archived":false,"fork":false,"pushed_at":"2026-05-17T05:15:36.000Z","size":134,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T07:04:24.332Z","etag":null,"topics":["ai-agents","freight","logistics","mcp","model-context-protocol"],"latest_commit_sha":null,"homepage":"https://www.freightutils.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SoapyRED.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T05:22:50.000Z","updated_at":"2026-05-17T05:15:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SoapyRED/freightutils-mcp","commit_stats":null,"previous_names":["soapyred/freightutils-mcp"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/SoapyRED/freightutils-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoapyRED%2Ffreightutils-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoapyRED%2Ffreightutils-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoapyRED%2Ffreightutils-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoapyRED%2Ffreightutils-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SoapyRED","download_url":"https://codeload.github.com/SoapyRED/freightutils-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoapyRED%2Ffreightutils-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33726719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","freight","logistics","mcp","model-context-protocol"],"created_at":"2026-05-17T07:02:19.160Z","updated_at":"2026-05-31T10:00:54.808Z","avatar_url":"https://github.com/SoapyRED.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FreightUtils MCP Server\n\n[![npm version](https://img.shields.io/npm/v/freightutils-mcp)](https://www.npmjs.com/package/freightutils-mcp)\n[![npm downloads (total)](https://img.shields.io/npm/dt/freightutils-mcp)](https://www.npmjs.com/package/freightutils-mcp)\n[![npm downloads (month)](https://img.shields.io/npm/dm/freightutils-mcp)](https://www.npmjs.com/package/freightutils-mcp)\n[![License: MIT](https://img.shields.io/npm/l/freightutils-mcp)](https://opensource.org/licenses/MIT)\n[![FreightUtils MCP server](https://glama.ai/mcp/servers/SoapyRED/freightutils-mcp/badges/score.svg)](https://glama.ai/mcp/servers/SoapyRED/freightutils-mcp)\n\nA [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI agents access to 19 freight calculation and reference tools, covering road, air, and sea freight.\n\nBuilt by an ADR-certified freight transport planner for AI agents, developers, and freight professionals.\n\n**Website:** https://www.freightutils.com\n**API Docs:** https://www.freightutils.com/api-docs\n\n---\n\n## Tools (19)\n\n### Calculators\n| Tool | Description |\n|------|-------------|\n| `ldm_calculator` | Loading metres for European and US road trailers |\n| `cbm_calculator` | Cubic metres for sea freight |\n| `chargeable_weight_calculator` | Air freight chargeable weight (volumetric vs actual) |\n| `pallet_fitting_calculator` | Box-on-pallet optimisation with rotation |\n| `container_lookup` | ISO container specs (10 types) and loading calculation |\n| `unit_converter` | Weight, volume, length, and freight-specific conversions |\n| `consignment_calculator` | Multi-item CBM, weight, LDM, chargeable weight |\n\n### Dangerous Goods (ADR)\n| Tool | Description |\n|------|-------------|\n| `adr_lookup` | 2,939 UNECE ADR 2025 entries |\n| `adr_exemption_calculator` | ADR 1.1.3.6 small load exemption check |\n| `adr_lq_eq_check` | Limited and Excepted Quantity eligibility |\n\n### Customs \u0026 Tariff\n| Tool | Description |\n|------|-------------|\n| `hs_code_lookup` | 6,940 Harmonized System tariff codes (HS 2022) |\n| `uk_duty_calculator` | UK import duty and VAT (live GOV.UK Trade Tariff data) |\n| `incoterms_lookup` | Incoterms 2020 — all 11 rules with risk/cost transfer points |\n\n### Reference Data\n| Tool | Description |\n|------|-------------|\n| `airline_lookup` | 6,352 airlines with IATA/ICAO codes and AWB prefixes |\n| `unlocode_lookup` | 116,129+ UN/LOCODE transport locations |\n| `uld_lookup` | 16 air cargo ULD types (LD3, PMC, etc.) |\n| `vehicle_lookup` | 17 road freight vehicles and trailers |\n\n### Composite\n| Tool | Description |\n|------|-------------|\n| `shipment_summary` | Chains CBM + weight + LDM + ADR + duty in one call |\n\n### Subscription\n| Tool | Description |\n|------|-------------|\n| `get_subscribe_link` | URL to upgrade to FreightUtils Pro (50,000/month at £19/mo) |\n\n---\n\n## Installation\n\n### Claude Desktop / Claude Code (stdio)\n\nAdd to your MCP config (`claude_desktop_config.json` or `.claude/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"freightutils\": {\n      \"command\": \"npx\",\n      \"args\": [\"freightutils-mcp\"]\n    }\n  }\n}\n```\n\n### Remote HTTP / SSE\n\nIf your MCP client supports remote servers, use the canonical URL:\n\n```\nhttps://www.freightutils.com/api/mcp\n```\n\n\u003e The older URL `https://www.freightutils.com/api/mcp/mcp` still works for backwards compatibility with existing clients.\n\nNo authentication required for basic usage.\n\n---\n\n## Verify your setup\n\nAfter 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.\n\nThen run the install diagnostic from a terminal:\n\n```sh\nnpx freightutils-mcp ping\n```\n\nYou should see three ticks and `All checks passed`:\n\n```\nFreightUtils MCP Diagnostic\n───────────────────────────\npackage: freightutils-mcp@2.2.0\nhealth:  https://www.freightutils.com/api/mcp/health\n\n[1/3] Backend health (https://www.freightutils.com/api/mcp/health)\n      ✓ status=ok mcp_version=2.2.0 tools_registered=19 (143ms)\n\n[2/3] MCP handshake (in-process via InMemoryTransport)\n      ✓ server freightutils-mcp@2.2.0 initialized; tools/list returned 19 tools\n\n[3/3] End-to-end tool call (cbm_calculator l=120 w=80 h=100)\n      ✓ cbm_calculator → total=0.96 m³ (expected 0.96) (218ms)\n\nAll checks passed. Your FreightUtils MCP install is working.\n```\n\nIf any check shows ✗, see [Troubleshooting](#troubleshooting) below. Exit code is 0 on all-pass and 1 on any failure, so the command works in CI / health-check scripts too.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---------|--------------|-----|\n| 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. |\n| `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=\u003cbase-url\u003e`. |\n| `npx freightutils-mcp ping` check 2 fails | Broken local install (npx cache or stale Node version) | Re-install: `rm -rf ~/.npm/_npx \u0026\u0026 npm install -g freightutils-mcp` and rerun. Requires Node 18 or newer. |\n| Tool calls return HTTP 429 / `\"rate_limited\"` | Anonymous IP cap of 25 requests/day exceeded | Get a free API key at https://www.freightutils.com/api-docs (100/day) or upgrade to Pro (50,000/month). **Known limitation:** this npm package does not yet pass the API key through. Until that lands, configure your MCP client to use the remote URL directly (`https://www.freightutils.com/api/mcp`) and set the `Authorization` header in the client config if your client supports it. |\n| `\"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. |\n| 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](https://www.freightutils.com/playground) endpoint to confirm the input shape. |\n\nThe full diagnostic flow lives at the [/api-docs#mcp-setup](https://www.freightutils.com/api-docs#mcp-setup) section on the website. The live backend status is callable from inside any MCP client at [GET /api/mcp/health](https://www.freightutils.com/api/mcp/health) — useful when you don't have shell access during a conversation.\n\n---\n\n## Rate Limits\n\nAll tools call the free FreightUtils API:\n\n- **Anonymous:** 25 requests/day per IP\n- **Free API key:** 100 requests/day (register at https://www.freightutils.com)\n- **Pro:** 50,000 requests/month at £19/month\n\n---\n\n## Example Prompts\n\nOnce connected, your AI agent can:\n\n- \"Calculate CBM for a box 120cm × 80cm × 100cm, 24 pieces\"\n- \"Look up UN 1203 in the ADR database\"\n- \"Check if 200L of petrol qualifies for ADR 1.1.3.6 exemption\"\n- \"Find the HS code for lithium batteries\"\n- \"What does FOB mean in shipping?\"\n- \"How many boxes of 40×30×25cm fit on a euro pallet?\"\n- \"Calculate loading metres for 26 euro pallets on an artic trailer\"\n- \"What's the UK import duty on laptops from China?\"\n\n---\n\n## Data Sources\n\n- **ADR 2025** — UNECE (licensed from Labeline.com)\n- **HS 2022** — UN Comtrade (PDDL)\n- **Airlines** — public IATA/ICAO data, cross-referenced\n- **UN/LOCODE** — UNECE\n- **UK Duty** — live GOV.UK Trade Tariff API\n- **Containers/ULD/Vehicles** — ISO, IATA, and industry-standard specifications\n\n---\n\n## Changelog\n\nFull release notes also on [GitHub Releases](https://github.com/SoapyRED/freightutils-mcp/releases).\n\n### 2.1.1 — 2026-05-09\n- **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.\n- **Fix:** `server.json` description undercounted tools (`\"18 freight tools …\"` → `\"19 freight tools …, get_subscribe_link\"`).\n- **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.\n\n### 2.1.0 — 2026-05-01\n- **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.**\n- 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.\n\n### 2.0.0 — 2026-04-25 (BREAKING — input-side casing)\n- **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.**\n- 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.\n\n### 1.1.0 — 2026-04-25 (BREAKING — response-side casing)\n- **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.**\n- 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.\n- README badges: added monthly + total npm downloads alongside the existing version + license + Glama score badges.\n\n### 1.0.8 — 2026-04-23 (hotfix)\n- **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.\n- Server identity bumped: `version: '1.0.7'` → `'1.0.8'`.\n- No other changes. 18 tools, annotations, `shipment_summary` descriptions, and `smithery.yaml` from 1.0.7 are preserved.\n\n### 1.0.7 — 2026-04-22\n- Add `smithery.yaml` with empty configSchema (Smithery Quality Score: config UX +25).\n- Add read-only `annotations` to all 18 tools (`readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`) with human-readable `title` (+7).\n- Add missing parameter `.describe(...)` text to `shipment_summary` (+1).\n- Add stub `list_prompts` / `list_resources` handlers so probes return `{ prompts: [] }` / `{ resources: [] }` instead of `-32601 Method not found` (+5).\n- Fix server identity: `name: 'FreightUtils'` → `'freightutils-mcp'`, `version: '1.0.0'` → `'1.0.7'`.\n- No breaking changes. Same 18 tools, same names, same behaviour.\n\n### 1.0.6 — 2026-04-22\n- 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](https://github.com/advisories/GHSA-345p-7cg4-v4c7).\n- No user-facing API changes. Same 18 tools.\n\n---\n\n## Other ways to use FreightUtils\n\nFreightUtils ships across multiple distribution surfaces. Pick the one that fits how you work:\n\n- **Website** — interactive tools at [freightutils.com](https://www.freightutils.com)\n- **REST API** — 19 endpoints, free tier (100/day) and Pro tier (50K/month, £19/mo). [API docs](https://www.freightutils.com/api-docs)\n- **MCP server** — for LLM agents and AI tooling. [npm: freightutils-mcp](https://www.npmjs.com/package/freightutils-mcp) · [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=freightutils)\n- **n8n custom node** — for workflow automation. [npm: n8n-nodes-freightutils](https://www.npmjs.com/package/n8n-nodes-freightutils)\n\nSame data, same compliance reference set (ADR 2025, HS 2022, IATA-regulated airline prefixes), every surface kept in sync.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\nBuilt by [Marius Cristoiu](https://www.linkedin.com/in/marius-cristoiu-a853812a2/), ADR-certified freight transport planner.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoapyred%2Ffreightutils-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoapyred%2Ffreightutils-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoapyred%2Ffreightutils-mcp/lists"}