FreightUtils MCP Server

FreightUtils MCP サーバー

AI エージェントのための、中立的な貨物輸送リファレンスレイヤーです。

FreightUtils は、AI エージェントのための中立的な貨物輸送リファレンスレイヤーです。一次資料（ADR 2025 / UNECE、HS 2022 / WCO、IATA 規制対象の航空会社プレフィックス）に基づく、危険物、税関、所在地、貨物計算のデータを、エージェントが呼び出して引用できます。中立性を重視して設計されており、販売する貨物も、特定の運送会社を推すこともありません。検索結果には、指定された情報源の記載内容と引用が付属するため、エージェントは当社の言葉を鵜呑みにせず、自ら確認できます。貨物を誰が運送する場合も同様です。

この Model Context Protocol サーバーにより、AI エージェントは道路、航空、海上貨物輸送を対象とした25種類の貨物計算・参照ツールを利用できます。英国の ADR 認定貨物輸送プランナーが開発しました。

すべての応答には情報源が引用されています。権威機関、版、保有している場合はライセンス、エージェントが読み取れる検証ステータスを含む _source ブロックが付属します。また、ツールは決定論的であり、回答を生成するものではありません。あくまで参照用であり、申告、予約、法的助言には使用できません。結果には、人による確認が必要な場合が明記されます（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	IATA/ICAO コードと AWB プレフィックスを含む 6,356 社の航空会社
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（modulus-7）、IMO 番号を検出して検証します。または、種類を指定して単一の識別子を検証します

複合

ツール	説明
shipment_summary	CBM + 重量 + LDM + ADR + 関税を 1 回の呼び出しで連続して処理

プラン

ツール	説明
get_subscribe_link	Pro プランの上限と料金（1 か月あたり 50,000 回、月額 £19）が記載された料金ページの URL

---

インストール

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 アドレスごとに 1 日 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（無料、1 日 100 リクエスト）または freightutils.com/pricing（Pro、月 50,000 リクエスト）で取得できます。後方互換性があり、環境変数を設定しなければ、従来の匿名動作が維持されます。

キーが設定されていない場合、サーバーは起動時に stderr へその旨を一度だけ出力します（stdout には MCP プロトコルのみが出力されます）。設定するつもりだったキーを設定し忘れた場合も、最初の 429 エラーが発生する前に、クライアントの MCP ログで確認できます。

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

3 つのチェックマークと 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 を設定してください。ping のホストを変更するには FREIGHTUTILS_API_URL=<base-url> を指定します。
npx freightutils-mcp ping のチェック 2 が失敗する	ローカルインストールの破損（npx キャッシュまたは古い Node バージョン）	再インストールしてください：rm -rf ~/.npm/_npx && npm install -g freightutils-mcp を実行してから、再度実行します。Node 18 以降が必要です。
ツール呼び出しで HTTP 429 / "rate_limited" が返る	匿名利用の IP アドレスごとの 1 日 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 のスキーマを確認するか、対応する プレイグラウンド のエンドポイントを呼び出して、入力形式を確認してください。

診断の全手順は、ウェブサイトの /api-docs#mcp-setup セクションにあります。稼働中のバックエンドのステータスは、GET /api/mcp/health から任意の MCP クライアント内で確認できます。会話中にシェルへアクセスできない場合に便利です。

---

レート制限

すべてのツールは、無料の FreightUtils API を呼び出します。

• 匿名： IP アドレスごとに 1 日 25 リクエスト
• 無料 API キー： 1 日 100 リクエスト（https://www.freightutils.com で登録）
• Pro： 月額 £19 で月 50,000 リクエスト

---

セキュリティとデータ

• 読み取り専用です。 すべてのツールは検索または計算を行い、readOnlyHint: true および destructiveHint: false として宣言されています。サーバーはどこに対しても変更を加えません。
• ファイルシステムもシェルも使用しません。 サーバーが読み取るファイルは自身の package.json だけで、プロセスを起動せず、ポートも開きません。通信は stdio のみで行います。
• 送信先は1つです。 ツールの入力は HTTPS 経由で https://www.freightutils.com/api（または FREIGHTUTILS_API_URL で設定したベース URL）にのみ送信されます。get_subscribe_link はローカルで応答し、何も送信しません。
• キーは環境変数に保持されます。 FREIGHTUTILS_API_KEY は環境変数から読み取られ、そのホストへの Authorization: Bearer ヘッダーとしてのみ送信されます。ログに記録されたり、ディスクに書き込まれたり、エラーメッセージに含まれたりすることはありません。
• stdout はプロトコル用です。 stdout に出力されるのは MCP JSON-RPC のみです。起動時の通知は stderr に出力されます。
• 検証は2段階で行われます。 各ツールの Zod スキーマが、呼び出し前に型、形式、API 独自の制限をチェックします（3つの ADR ツール、adr_exemption_calculator、adr_lq_eq_check、shipment_summary は、読み取らないフィールドを名前で指定して拒否します）。その後、API がサーバー上ですべてのリクエストを再検証し、回答できないリクエストはフィールド名を示した 400 エラーで拒否します。
• エラーの種類が分かるように報告します。 呼び出しの失敗は、ネットワーク障害、タイムアウト（30 秒、または FREIGHTUTILS_TIMEOUT_MS で指定）、API 独自の 4xx 拒否、reset_at を含む 429、または 5xx として報告されます。スタックトレース、リクエストヘッダー、サーバーエラーページの内容が含まれることはありません。
• 実行時の直接依存関係は2つです。 @modelcontextprotocol/sdk と zod です。本番依存関係ツリーに重大度が high または critical のアドバイザリがある場合、CI は失敗し、Dependabot が監視します。
• 脆弱性の報告： SECURITY.md を参照してください。

---

プロンプトの例

接続すると、AI エージェントは次のような操作を行えます。

• 「120cm × 80cm × 100cm の箱、24個分の CBM を計算して」
• 「ADR データベースで UN 1203 を調べて」
• 「ガソリン 200L が ADR 1.1.3.6 の免除対象になるか確認して」
• 「リチウム電池の HS コードを調べて」
• 「輸送における FOB の意味は？」
• 「40×30×25cm の箱は、ユーロパレットに何個載る？」
• 「大型トレーラーにユーロパレット 26 枚を積載する場合の積載メートル数を計算して」
• 「中国からノート PC を輸入する場合、英国の輸入関税はいくら？」

---

データソース

• ADR 2025 — UNECE、ECE/TRANS/352、2025年1月1日適用。EU 指令 2008/68/EC（統合版）により法的効力が付与されています。事実に基づく編集資料で、可能な限り正確を期していますが、法律上の助言ではなく、規制当局による情報でもありません。
• HS 2022 — UN Comtrade の H6 分類（UN Statistics Division）に基づく HS 2022 の説明。WCO が Harmonized System の品目表を管理しています。明示されたオープンライセンスはありません。
• 航空会社 — 公開情報をもとに 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が後継リリースに置き換わった後も、3つのディレクトリで3か月間、2.4.0が最新リリースとして表示されていました。現在は情報源を1つにまとめています。

---

FreightUtilsを利用するその他の方法

FreightUtilsは複数の配布形態で提供されています。使い方に合ったものをお選びください。

• ウェブサイト — freightutils.comで利用できるインタラクティブなツール
• REST API — 24個のエンドポイント、無料プラン（1日100回）とProプラン（月50,000回、£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規制対象の航空会社プレフィックス）を使用し、すべての形態で同期を保っています。

---

ライセンス

MIT — LICENSEをご覧ください。

マリウス・クリストイウが開発。ADR認定の貨物輸送プランナーです。