FreightUtils MCP Server 是面向 AI 智能体的中立货运参考层，由英国 ADR 认证货运运输规划师 Marius Cristoiu 构建。它提供来源可查、可引用的危险品、海关、地点和货运计算数据，数据取自主要来源（ADR 2025 / UNECE、HS 2022 / WCO、IATA 监管的航空公司前缀）。设计上保持中立：不销售货运，不推销承运商——查询返回指定来源的内容，并附带引用，使智能体可以自行检查，而非仅凭其声明。
用途 该 Model Context Protocol 服务器为 AI 智能体提供 25 个货运计算和参考工具，覆盖公路、航空和海运货运。每个响应都引用其来源——一个 _source 块，包含权威机构、版本、所持许可证（如有）以及智能体可读取的验证状态。工具是确定性的，不是生成的答案。仅作参考：从不进行申报、订舱或提供法律建议，结果会说明何时需要人工审核（validate 仅为结构性校验位验证；干净的 ics2_check 不代表 ENS 被接受；排放数据为估算值，非审计报告）。
主要能力 自 2.11.0 起，每个工具还声明类型化 outputSchema 并返回 structuredContent——FreightUtils v1 响应信封：结果位于 result 下，外加 confidence、normalized_input、warnings、_source 和可直接使用的 citation。旧版扁平 JSON 文本通道保持不变（字节级相同），因此现有文本解析消费者不受影响。
危险品（ADR）：部分 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 编码查询、关税估算等。
使用方式 Claude（claude.ai、桌面和移动应用、Cowork）：从 Claude 的连接器目录添加 FreightUtils：https://claude.ai/directory/connectors/freightutils。或作为自定义连接器添加——Customize → Connectors → Add custom connector——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）。
远程 HTTP / SSE：如果 MCP 客户端支持远程服务器，使用规范 URL。旧 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 传输已支持同一密钥。密钥获取：freightutils.com/api-docs（免费，100/天）或 freightutils.com/pricing（Pro，50,000/月）。向后兼容——未设置环境变量则保持现有匿名行为。未设置密钥时，服务器在启动时通过 stderr 说明一次（stdout 仅承载 MCP 协议），以便遗漏的密钥出现在客户端 MCP 日志中，而非首次 429 时。
验证设置：将 FreightUtils 添加到 MCP 客户端配置后，完全退出并重新启动客户端（Claude Desktop、Cursor、Cline）。MCP 服务器仅在客户端启动时加载；在运行会话中编辑配置无效，直到重启。然后从终端运行安装诊断。应看到三个勾选和 All checks passed。如有检查显示 ✗，见故障排除。退出码全通过为 0，任何失败为 1，因此该命令也可用于 CI / 健康检查脚本。
故障排除：完整诊断流程见网站 /api-docs#mcp-setup 部分。实时后端状态可在任何 MCP 客户端内通过 GET /api/mcp/health 调用——在对话中无 shell 访问时有用。
适用场景 所有工具调用免费的 FreightUtils API：匿名每 IP 每天 25 次请求；免费 API 密钥每天 100 次（在 https://www.freightutils.com 注册）；Pro 每月 50,000 次请求，19 英镑/月。
示例提示：连接后，AI 智能体可以：计算 120cm × 80cm × 100cm 箱子 24 件的 CBM；在 ADR 数据库中查询 UN 1203；检查 200L 汽油是否符合 ADR 1.1.3.6 豁免；查找锂电池的 HS 编码；FOB 在运输中是什么意思；40×30×25cm 的箱子能装多少个到欧洲托盘上；计算 26 个欧洲托盘在铰接式拖车上的装载米数；从中国进口笔记本电脑的英国进口关税是多少。
安全与数据 只读。每个工具都是查询或计算，声明 readOnlyHint: true 和 destructiveHint: false。服务器不改变任何地方。无文件系统，无 shell。服务器除自身 package.json 外不读取任何文件，不启动进程，不打开端口——仅通过 stdio 通信。单一目的地。工具输入仅发送到 https://www.freightutils.com/api（或 FREIGHTUTILS_API_URL 设置的基础地址），通过 HTTPS。get_subscribe_link 本地应答，不发送任何内容。密钥保留在环境中。FREIGHTUTILS_API_KEY 从环境读取，仅作为 Authorization: Bearer 头发送到该主机——从不记录、从不写入磁盘、从不放入错误消息。stdout 是协议。除 MCP JSON-RPC 外无内容进入 stdout；唯一的启动通知进入 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。
数据来源 ADR 2025——UNECE，ECE/TRANS/352，2025 年 1 月 1 日适用；由欧盟指令 2008/68/EC（合并版）赋予法律效力。事实汇编，尽力而为——非法律建议，非监管机构。HS 2022——HS 2022 描述来自 UN Comtrade 的 H6 分类（UN 统计司）；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 中并复制于此，而非凭记忆编写——因此在那里重新归属的来源不能继续在此引用。
其他使用方式 FreightUtils 跨多个分发渠道发布。选择适合您工作方式的：网站——freightutils.com 的交互式工具；REST API——24 个端点，免费层（100/天）和 Pro 层（50K/月，19 英镑/月），API 文档；MCP 服务器——用于 LLM 智能体和 AI 工具，npm: freightutils-mcp · MCP Registry；n8n 自定义节点——用于工作流自动化，npm: n8n-nodes-freightutils；自定义 GPT——OpenAI GPT Store 上的 FreightUtils GPT，由同一 OpenAPI 规范支持。相同数据，相同合规参考集（ADR 2025、HS 2022、IATA 监管的航空公司前缀），每个渠道保持同步。
限制 仅作参考，不提供申报、订舱或法律建议。结果会说明何时需要人工审核。validate 仅为结构性校验位验证；干净的 ics2_check 不代表 ENS 被接受；排放数据为估算值，非审计报告。匿名使用上限为每 IP 每天 25 次请求。许可证：MIT——见 LICENSE。
