FreightUtils MCP Server

FreightUtils MCP 服务

面向 AI Agent 的中立货运参考层。

FreightUtils 是面向 AI Agent 的中立货运参考层，提供有来源依据的危险品、海关、地点和货运计算数据，Agent 可调用并引用这些数据。数据来自一手来源（ADR 2025 / UNECE、HS 2022 / WCO、受 IATA 监管的航空公司前缀）。秉持中立原则：不销售货运服务，也不偏袒任何承运人。查询结果会返回指定来源的原文，并附上引用，方便 Agent 检查，而非盲目采信；无论货物由谁承运，结果均如此。

这个模型上下文协议服务为 AI Agent 提供 25 种货运计算和参考工具，涵盖公路、航空和海运。由一位获得英国 ADR 认证的货运运输规划师开发。

每条响应都会引用来源：_source 块包含机构、版本、许可信息（如有）以及 Agent 可读取的核验状态。工具的结果是确定性的，并非生成式回答。仅供参考：不能用于申报或预订，也不构成法律建议；结果会注明何时需要人工审核（validate 仅进行结构性校验和位验证；ics2_check 通过不代表 ENS 已获接受；排放数据为估算值，并非经审计的报告）。

自 2.11.0 起，每个工具还会声明类型化的 outputSchema 并返回 structuredContent——FreightUtils v1 响应封装：在 result 下提供答案，另含 confidence、normalized_input、warnings、_source 和可直接使用的 citation。原有的扁平 JSON 文本通道保持不变（字节完全一致），因此现有的文本解析使用方不会受到影响。

网站： https://www.freightutils.com API 文档： https://www.freightutils.com/api-docs

---

工具（25）

计算器

工具	说明
ldm_calculator	计算欧洲和美国公路拖车的装载米数
cbm_calculator	计算海运货物的立方米数
chargeable_weight_calculator	计算空运计费重量（体积重量与实际重量）
pallet_fitting_calculator	通过旋转优化纸箱在托盘上的摆放
container_lookup	查询 ISO 集装箱规格（10 种类型）并计算装载量
unit_converter	换算重量、体积、长度及货运专用单位
consignment_calculator	计算多件货物的 CBM、LDM、体积重量和按运输方式区分的计费重量（海运/空运/公路），并提供建议标记
emissions_calculator	使用 ISO 14083 / GLEC 基于距离的方法计算货运 CO2e——采用开放的 DEFRA/EPA/ADEME 系数（WTW + TTW）；使用实际总质量（而非计费重量/体积重量）；结果包含 empty_running + representativeness（海运/空运 = 低）以及摘要

危险品（ADR）

工具	描述
adr_lookup	2,939 条 UNECE ADR 2025 记录
adr_exemption_calculator	ADR 1.1.3.6 小批量豁免检查
adr_lq_eq_check	有限数量和例外数量适用性

部分 UN 编号在 ADR 表 A 中有多行记录（包装类别、浓度范围）。如果一个未附加其他条件的 UN 编号匹配到答案不同的记录，ADR 工具不会自行选择：它们会暂不提供判定并返回候选记录，你可以用 packing_group 或 variant_index 指定一项。规则和示例案例（UN 1789、UN 1790 PG I、UN 2215 PG III）：API 文档中的 ADR 1.1.3.6 计算器。

海关与关税

工具	描述
hs_code_lookup	6,940 个协调制度关税代码（HS 2022）
uk_duty_calculator	英国进口关税和 VAT（实时 GOV.UK Trade Tariff 数据）
incoterms_lookup	Incoterms 2020——全部 11 条规则及风险／费用转移节点
ics2_check	提交 ENS 前标记 EU ICS2 不可接受的货物描述术语（停用词）——仅供参考

参考数据

工具	描述
resolve_reference	当类型未知时，将任意货运标识符（“176”、“UN1845”、“NLRTM”、“FOB”）解析为类型明确、排序并附有引用的候选项
airline_lookup	6,356 家航空公司及其 IATA／ICAO 代码和 AWB 前缀
unlocode_lookup	116,232+ 个 UN/LOCODE 运输地点
airport_lookup	按 IATA／ICAO 代码、名称或城市查找 85,555 个机场（OurAirports）
nearest_airport	按大圆距离查找距离指定纬度／经度最近的机场
uld_lookup	16 种空运 ULD 类型（LD3、PMC 等）
vehicle_lookup	17 种公路货运车辆和拖车

验证

工具	描述
validate	解析任意文本（订舱行、电子邮件），找出并验证其中的所有集装箱（ISO 6346）、AWB（模 7）和 IMO 编号；也可按类型验证单个标识符

组合工具

工具	描述
shipment_summary	一次调用串联计算 CBM + 重量 + LDM + ADR + 关税

套餐

工具	描述
get_subscribe_link	定价页面 URL，其中包含 Pro 套餐的限额和价格（每月 50,000 次，£19／月）

---

安装

Claude（claude.ai、桌面和移动应用、Cowork）

从 Claude 的连接器目录添加 FreightUtils：https://claude.ai/directory/connectors/freightutils。也可以将其添加为自定义连接器——自定义 → 连接器 → 添加自定义连接器——并使用 URL https://www.freightutils.com/api/mcp。无需 API 密钥，也无需登录。设置、限额和隐私说明：freightutils.com/mcp#use-in-claude。

Claude Desktop / Claude Code（stdio）

将以下内容添加到 MCP 配置（claude_desktop_config.json 或 .claude/settings.json）：

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

远程 HTTP / SSE

如果你的 MCP 客户端支持远程服务，请使用规范 URL：

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

较旧的 URL https://www.freightutils.com/api/mcp/mcp 仍可使用，以兼容现有客户端。

开始使用无需 API 密钥——匿名调用开箱即用（请参阅下文的速率限制）。

使用 Pro 密钥进行身份验证

匿名使用的上限为每个 IP 每天 25 次请求。如果你有免费或 Pro API 密钥，请在运行 MCP 服务的环境中设置 FREIGHTUTILS_API_KEY。该软件包会从 process.env 中读取它，并在每次发出的 /api/* 调用中附加 Authorization: Bearer <key>——远程 https://www.freightutils.com/api/mcp 传输也已支持同一个密钥。

通过环境变量进行配置的 stdio 示例：

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

可在 freightutils.com/api-docs 获取密钥（免费，每天 100 次请求），或在 freightutils.com/pricing 获取 Pro 密钥（每月 50,000 次请求）。向后兼容——不设置环境变量即可保留现有的匿名使用方式。

未设置密钥时，服务会在启动时通过 stderr 提示一次（stdout 仅传输 MCP 协议）。这样，忘记设置的密钥会显示在客户端的 MCP 日志中，而不是等到首次出现 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

---

验证设置

将 FreightUtils 添加到 MCP 客户端配置后，请完全退出并重新启动客户端（Claude Desktop、Cursor、Cline）。MCP 服务仅在客户端启动时加载；在运行中的会话里编辑配置，只有重启后才会生效。

然后在终端中运行安装诊断：

npx freightutils-mcp ping

你应该会看到三个勾号和 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.

如果任何检查显示 ✗，请参阅下文的故障排除。所有检查通过时退出代码为 0，任何检查失败时为 1，因此该命令也可用于 CI / 健康检查脚本。

---

故障排除

症状	可能原因	解决方法
编辑配置后，MCP 客户端中没有显示工具	客户端未完全重启	退出并重新启动（macOS 上按 Cmd+Q / Windows 系统托盘中右键 → 退出）。仅关闭窗口并不足够。
npx freightutils-mcp ping 的检查 1 因网络错误而失败	DNS、代理问题，或你的网络无法访问该网站	查看 https://www.freightutils.com/status 上的状态页面。如果你使用企业代理，请设置 HTTPS_PROXY。可通过 FREIGHTUTILS_API_URL=<base-url> 为 ping 指定主机。
npx freightutils-mcp ping 的检查 2 失败	本地安装损坏（npx 缓存或 Node 版本过旧）	重新安装：rm -rf ~/.npm/_npx && npm install -g freightutils-mcp，然后重新运行。需要 Node 18 或更高版本。
工具调用返回 HTTP 429 / "rate_limited"	超出匿名 IP 每天 25 次请求的上限	如果你有 FreightUtils Pro API 密钥，请在调用 MCP 之前，在环境中设置 FREIGHTUTILS_API_KEY。该软件包会在每次发出的调用中自动传递此密钥。如需获取密钥，请访问 https://www.freightutils.com/pricing。
客户端日志中出现 "Server failed to start" / spawn 错误	npx 不在 PATH 中，或 Node 版本低于 18	安装 Node 18 或更高版本。在 macOS 上，在配置中使用绝对路径（"command": "/opt/homebrew/bin/npx"），可避免通过 GUI 启动的客户端遇到 PATH 问题。
特定工具返回 isError: true	输入格式错误，或查找键未知（数据集中不存在对应的 UN 编号 / HS 编码 / AWB 前缀）	工具的错误正文会指出有问题的字段。请参照 https://www.freightutils.com/api-docs 中的架构进行验证，或调用对应的 playground 端点确认输入格式。

完整的诊断流程见网站上的 /api-docs#mcp-setup 部分。可在任何 MCP 客户端内调用实时后端状态接口 GET /api/mcp/health——在对话期间无法访问 shell 时，这个接口很有用。

---

速率限制

所有工具都会调用免费的 FreightUtils API：

• **匿名：**每个 IP 每天 25 次请求
• **免费 API 密钥：**每天 100 次请求（在 https://www.freightutils.com 注册）
• **Pro：**每月 £19，可调用 50,000 次请求

---

安全与数据

• 只读。 每个工具都用于查询或计算，并声明 readOnlyHint: true 和 destructiveHint: false。服务不会在任何地方更改任何内容。
• 不访问文件系统，不使用 Shell。 除了自身的 package.json，服务不会读取任何文件；不会启动进程，也不会打开端口——仅通过 stdio 通信。
• 只有一个目标地址。 工具输入只会通过 HTTPS 发送到 https://www.freightutils.com/api（或你在 FREIGHTUTILS_API_URL 中设置的基础地址）。get_subscribe_link 会在本地作出响应，不会发送任何内容。
• 密钥保存在环境变量中。 FREIGHTUTILS_API_KEY 从环境变量中读取，且仅作为 Authorization: Bearer 请求头发送到该主机——绝不记录日志、写入磁盘或放入错误消息中。
• stdout 是协议通道。 stdout 中只会输出 MCP JSON-RPC；唯一的启动通知会发送到 stderr。
• 两层验证。 每个工具的 Zod 架构都会在发起调用前检查类型、格式和 API 自身的限制（三个 ADR 工具——adr_exemption_calculator、adr_lq_eq_check、shipment_summary——还会按名称拒绝不读取的字段）。随后，API 会在服务端再次验证每个请求，并对无法处理的请求返回 400 错误，同时指出字段名称。
• 错误保留其含义。 调用失败时会按类型报告：网络故障、超时（30 秒，或 FREIGHTUTILS_TIMEOUT_MS）、API 自身的 4xx 拒绝、带有 reset_at 的 429，或 5xx——绝不会包含堆栈跟踪、请求头或服务器错误页面的内容。
• 两个直接运行时依赖项： @modelcontextprotocol/sdk 和 zod。CI 会在生产依赖树中出现任何高危或严重安全公告时失败，Dependabot 也会持续监控。
• 报告漏洞： 请参阅 SECURITY.md。

---

示例提示词

连接后，你的 AI Agent 可以：

• “计算长 120cm × 宽 80cm × 高 100cm 的箱子的 CBM，共 24 件”
• “在 ADR 数据库中查询 UN 1203”
• “检查 200L 汽油是否符合 ADR 1.1.3.6 豁免条件”
• “查找锂电池的 HS 编码”
• “FOB 在货运中是什么意思？”
• “一个欧洲托盘能装多少个尺寸为 40×30×25cm 的箱子？”
• “计算一辆铰接式拖车装载 26 个欧洲托盘所需的装载米数”
• “从中国进口笔记本电脑到英国的关税是多少？”

---

数据来源

• ADR 2025 — UNECE，ECE/TRANS/352，自 2025 年 1 月 1 日起适用；由 EU 指令 2008/68/EC（合并版）赋予法律效力。尽力整理的事实汇编——不是法律建议，也不是监管机构。
• HS 2022 — UN Comtrade 的 H6 分类（UN Statistics Division）中的 HS 2022 描述；WCO 负责维护《协调制度》税则目录。未注明具体的开放许可。
• 航空公司 — 由 FreightUtils 根据公开来源汇编。已验证记录逐项引用承运人发布的页面和 FAA Order JO 7340.2；其余记录有待验证。IATA 和 ICAO 负责分配这些代码，但此数据集并非由 IATA 或 ICAO 发布或认可，也未对其作出许可或“开放数据”声明。
• UN/LOCODE 2025-1 — UNECE 官方发布文件，坐标经过严格验证。UN/LOCODE © UNECE，CC BY 4.0（按 UNECE 对 UN/CEFACT 标准的说明）。
• 英国关税 — 实时 GOV.UK Trade Tariff API，按请求获取，因此没有可能逐渐过时的本地副本。
• 集装箱 / ULD / 车辆 — ISO、IATA 和行业标准规范。
• 排放因子 — 已发布的 DEFRA / EPA / ADEME 因子（当前使用 DEFRA 2026 + EPA 2025 + ADEME Base Carbone v23.11），结合 ISO 14083 / GLEC 基于距离的方法计算。结果为估算值，不是经过审计的报告。

公开的来源说明在 FreightUtils 仓库的 docs/DATA_PROVENANCE.md 中维护，并复制于此处，而非凭记忆撰写——因此，若某个来源在那里更正了归属信息，此处也不会继续沿用旧说法。

---

更新日志

发布说明：此仓库中的 CHANGELOG.md 和 GitHub Releases。

README 自带一份更新日志，导致三个目录在 2.4.0 被后续版本取代三个月后，仍将 2.4.0 显示为最新版本。现在只有一个信息来源。

---

使用 FreightUtils 的其他方式

FreightUtils 通过多个渠道提供。请选择适合你工作方式的渠道：

• 网站 — freightutils.com 上的交互式工具
• REST API — 24 个端点，提供免费套餐（每天 100 次）和 Pro 套餐（每月 50K 次，£19/月）。API 文档
• MCP 服务 — 供大模型 Agent 和 AI 工具使用。npm: freightutils-mcp · MCP Registry
• n8n 自定义节点 — 用于工作流自动化。npm: n8n-nodes-freightutils
• 自定义 GPT — OpenAI GPT Store 上的 FreightUtils GPT，由同一份 OpenAPI 规范提供支持。

所有渠道使用相同的数据和合规参考集（ADR 2025、HS 2022、IATA 监管的航空公司前缀），并保持同步。

---

许可证

MIT — 参见 LICENSE。

由 Marius Cristoiu 构建，他是一名通过 ADR 认证的货运规划师。