Comtrade

UN Comtrade — 二国間貿易統計

国連統計部の貿易データベースです。報告国とすべての相手国との二国間貿易フローを、商品（HSコード）別に数十年にわたって収録しています。国レベルで「どの国が何をどこに輸出しているか」を調べる際の標準的な情報源です。

Pipeworx の一部です。Pipeworx は、AI エージェントを1875以上のライブデータソースに接続する MCP ゲートウェイです。これは独立した非公式の統合であり、上流プロバイダーとは提携も承認もされておらず、上流プロバイダーによる公開でもありません。

AI エージェントにとって重要な理由

エージェントが国際貿易に関する質問（貿易関係、商品フロー、背景を踏まえた関税、サプライチェーンの集中度など）に答える場合、Comtrade が情報源になります。データは構造化され（HSコード）、各国間で調和されているため、国をまたいだ比較の信頼性が高まります。

一般的なフロー：

• 二国間分析。 「2024年の米中貿易フロー。」→ comtrade_trade_data({reporter_code: "842", partner_code: "156", year: "2024"}) → 輸入＋輸出＋貿易収支。
• 主要商品。 「米国が中国から最も多く輸入しているものは？」→ comtrade_top_commodities({reporter_code, partner_code, flow: "M"})。
• 主要貿易相手国。 「米国の半導体を最も多く購入している国は？」→ comtrade_top_partners({reporter_code, hs_code: "8542", flow: "X"})。
• 国コードの検索。 ISOの3桁数値コードです。comtrade_country_codes で完全な対応表を取得できます。

trade_bilateral_analysis と trade_country_profile のコンパウンドで使用されています。

認証

Comtrade には無料プランとプレミアムプランがあります。無料プランはリクエスト数が厳しく制限されています（1分あたり数件）。より多く利用するには、https://comtradeplus.un.org で登録し、APIキーを _apiKey 経由で渡してください。

国および商品コード

種類	形式	例
国	ISO 3166-1数値コード	842（米国）、156（中国）、484（メキシコ）
商品	HSの章／項／号	85（電気機器）、8517（電話機）、851712（スマートフォン）
フロー	M / X / 再輸入 / 再輸出	M = 輸入、X = 輸出

comtrade_country_codes で完全な対応表を取得できます。名称の曖昧さによる問題を避けるため、ほとんどのエージェントは3桁の数値コードを渡します。

更新頻度

Comtrade のデータ公開には大幅な遅れがあり、通常は暦年の終了から6〜12か月後です。通常、クエリ可能な最新年は前年です。公開後はデータがほぼ変わらないため、Pipeworx は30日間のTTLでキャッシュします。

よくある落とし穴

• 報告国側と相手国側のミラーデータ。 貿易の両側が報告します（米国は中国からの輸入を報告し、中国は米国への輸出を報告します）。数値は完全には一致しません。評価方法（CIF対FOB）、輸送の扱い、分類の違いなどが原因です。報告国側のデータを使うのが慣例です。両方が必要な場合は、両方をリクエストしてください。
• HS改訂による変更。 HS分類は5年ごとに更新されます（HS17、HS22など）。長期時系列は改訂をまたぐため、同じ商品でもコードが変わることがあります。標準的なクエリでは、Comtrade が調和処理を行います。
• サービス貿易は含まれません。 Comtrade が対象とするのは物品のみです。サービス貿易は別の情報源（BEA／WTOのデータ）にあります。混同しないでください。
• 再輸出。 香港の「米国向け輸出」には、中国原産品の大規模な再輸出が含まれます。flow パラメーターで区別できるため、明示的に指定してください。
• 通貨。 デフォルト値はUSDですが、unit フィールドを確認してください。価額を報告せず、数量（kg、単位）のみを報告する系列もあります。
• 報告されていない国の組み合わせ。 毎年Comtradeに報告するとは限らない国もあります。キューバ、イラン、北朝鮮には大きな欠損があります。相手国側のミラーデータで補える場合があります。その国との貿易について、相手国の報告データをクエリしてください。

クイックスタート

MCP クライアント（Claude Desktop、Cursor、Windsurf など）に追加します：

{
  "mcpServers": {
    "comtrade": {
      "url": "https://gateway.pipeworx.io/comtrade/mcp"
    }
  }
}

このエンドポイントが実際に提供するもの

https://gateway.pipeworx.io/comtrade/mcp の tools/list は、上の表にあるツールに加えて、共有の Pipeworx メタツールも返します。ask_pipeworx、 discover_tools、search_within、remember／recall など、ゲートウェイ全体で使えるツール一式です。そのため、表示されるツール数はこの表より多くなります。現在、単一パックのエンドポイントには、パック固有のツールに加えて、共有ツールが約 30 個表示されます。接続の initialize 応答に正確な対象範囲が記載されており、その日の状況を確認する際の正式な情報源です。

これは意図的な設計であり、偶然の多重化ではありません。メタツールを使うことで、このパックの対象外の質問にも、カタログ全体を横断してルーティングする ask_pipeworx 経由で回答できるため、2 つ目の MCP サーバーを追加する必要がありません。現時点では、メタツールなしでパックのエンドポイントをマウントする方法はありません。追加のスキーマによるコンテキスト消費がルーティングの利点を上回る場合は、複数のパックエンドポイントではなく、フルゲートウェイに一度だけ接続してください。

または、Pipeworx のフルゲートウェイに接続して、このパックだけでなく、すべてのパックのツールを直接一覧表示できます。

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

どちらの URL も、同じゲートウェイと同じ 1875 以上のデータソースに接続します。違いは、どのパックのツールが直接一覧表示されるかだけです。どちらからでも、ask_pipeworx を使ってすべてのツールにアクセスできます。

MCP クライアントがない場合：HTTP で呼び出す

curl -X POST https://gateway.pipeworx.io/v1/tools/comtrade_trade_data \
  -H 'Content-Type: application/json' \
  -d '{"reporter_code":"842","partner_code":"156","year":"2024"}'

最初の呼び出しにアカウントは必要ありません。任意のツールを確認するには、GET https://gateway.pipeworx.io/v1/tools/comtrade_trade_data を実行します。ツールを検索するには、{"query":"..."} を指定して POST https://gateway.pipeworx.io/v1/tools/search_packs を実行します。

スタンドアロン（ゲートウェイアカウント不要）

このパッケージは、ローカルの stdio MCP サーバーとしても実行できます。Pipeworx アカウントも、ゲートウェイへのラウンドトリップも不要です。

{
  "mcpServers": {
    "comtrade": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-comtrade"]
    }
  }
}

または、直接実行して起動することを確認できます。

npx -y @pipeworx/mcp-comtrade

stdin/stdout 経由で MCP を使用し、このパックのツールのみを対象に initialize／tools/list／tools/call に応答します。上記のゲートウェイ接続で追加される共有メタツールはありません。同じソース、同じツールで、ask_pipeworx によるルーティングはありません。

ask_pipeworx の使用

ツールを直接呼び出す代わりに、自然な英語で質問できます。これは、上記のパックエンドポイントでもフルゲートウェイでも利用できます。

ask_pipeworx({ question: "your question about Comtrade data" })

ゲートウェイが適切なツールを選び、引数を自動的に設定します。

詳細

• ドキュメントとガイド
• pipeworx.io

ライセンス

MIT