un-comtrade-mcp-server

---

概要

国連Comtradeの国際的な財・サービス貿易統計を提供します。国およびHS商品コードを特定し、二国間の貿易フローやサービス貿易を取得できるほか、貿易収支、相手国・商品別ランキング、データの利用可能状況を算出できます。

ツール

ツール	説明
comtrade_lookup_countries	国名および地域名をComtrade M49数値コードに変換します。
comtrade_search_commodities	キーワード、説明、またはコードのプレフィックスでHS商品コードを検索します。
comtrade_list_service_categories	キーワードまたは親コードでEBOPS 2010サービス貿易カテゴリを一覧表示します。
comtrade_get_trade_flows	二国間の貿易フロー記録を取得します。期間・商品・相手国ごとの金額、数量、重量を確認できます。
comtrade_get_trade_balance	1つ以上の期間について、国の貿易収支（輸出から輸入を差し引いた値）を算出します。
comtrade_get_top_partners	報告国、商品、フローの方向に基づき、貿易額で取引相手国をランキングします。
comtrade_get_top_commodities	報告国とフローの方向に基づき、貿易額で商品カテゴリをランキングします。
comtrade_get_data_availability	データが公開されている報告国・期間・分類の組み合わせを確認します。
comtrade_get_services_trade	国際サービス貿易データ（EBOPS 2010）を取得します。

リソース

リソース	説明
comtrade://countries	M49コード、ISO識別子、報告国としての有効性を含む、国・地域コードの完全な一覧です。
comtrade://hs-classification/{level}	章、項、号の各レベルにおける、HS商品分類の最上位階層です。

どちらのリソースもツールから利用できます。comtrade_lookup_countries と comtrade_search_commodities では、同じデータをキーワード検索できます。

機能リファレンス

comtrade_lookup_countries _ツール

• 国名の一部または正式名称、あるいはISO alpha-2／alpha-3コードを指定できます。role では "reporter"、"partner"、"any"（デフォルト）で絞り込めます
• 各一致結果の validAsReporter フラグは、報告国として有効かどうかを示します（例：WorldやEUなどの地域グループは、パートナーとしては有効ですが、報告国としては無効です）
• include_groups（デフォルトは true）で、結果に地域・経済グループを含めるかどうかを切り替えられます
• 参照データは起動時にUNの静的ファイルから読み込まれるため、サブスクリプションキーは不要で、即座に応答します

---

comtrade_search_commodities _ツール

• フリーテキストのキーワード、説明の一部、またはコードの接頭辞で検索できます。classification では HS（統合データセット、デフォルト）または特定の版 H0～H6 を選択します
• aggr_level では 2（章）、4（項）、6（号）に絞り込めます。すべてのレベルを対象にする場合は省略します
• limit のデフォルトは50です。200を超える値を指定すると、一致するすべての結果が返されます。上限より少ない値に一致結果が収まらない場合は、truncated: true が返されます
• 各結果の recommendedQueryCode は、貿易クエリで cmd_code として渡すのに最適なコードです

---

comtrade_list_service_categories _ツール

• EBOPS 2010のサービス分類を一覧表示します。キーワードまたは parent_code で絞り込むこともできます
• limit のデフォルトは100です。500を超える値を指定すると、すべての分類が返されます。上限より少ない値に一致結果が収まらない場合は、truncated: true が返されます
• 返される id は、comtrade_get_services_trade で使用する service_code です

---

comtrade_get_trade_flows _ツール

• reporter_code、flow_code（M 輸入／X 輸出／RX 再輸出／RM 再輸入）、および period（YYYY または YYYYMM 形式）が必要です。最大120期間を指定できますが、提供されるのは先頭の12期間のみで、残りは unservedPeriods に一覧表示されます
• partner_code: 0 を指定すると世界合計が返されます。パートナー別の内訳を取得する場合は省略します。classification では HS、H0～H6、およびSITCの S1～S4／SS を指定できます（商品検索はHSのみ対応）
• cmd_code[] には最大200コードを指定できますが、提供されるのは先頭の20コードのみで、残りは unservedCmdCodes に一覧表示されます。商品分類をまたぐ合計を取得する場合は省略するか、["TOTAL"] を渡します。truncated: true と truncationHint は、応答が500件の上限に達したことを示します。isReported では、直接報告された行とUNによる推計値を区別します

---

comtrade_get_trade_balance _ツール

• 期間ごとに balanceUsd（符号付き）、exportsUsd、importsUsd、および coverageRatio（輸出／輸入）を返します。省略可能な cmd_code[] を指定すると、HSまたはSITCの商品に収支を絞り込めます
• 1回の呼び出しで12期間、20コードが提供されます（最大120期間、200コードまで受け付けます）。残りは unservedPeriods／unservedCmdCodes に一覧表示されます。いずれかのフローが500件の上限に達した場合、収支が不完全な可能性があることを notice で警告します
• すべての応答に含まれる mirrorCaveat は、収支がこの報告国自身の値を反映し、パートナー側のミラーデータを反映していないことを示します

---

comtrade_get_top_partners _ツール

• reporter_code、flow_code（M／X）、および単一の period を指定します。省略可能な単一の cmd_code を指定できます（商品全体の貿易を取得する場合は省略します）
• 最大 limit 件のパートナーを返します（デフォルトは10。50を超える値を指定すると、取得されたすべての結果が返されます）。各結果には rank、primaryValueUsd、sharePercent が含まれます
• 取得結果が500件の上限に達した場合は、truncated: true が返されます

---

comtrade_get_top_commodities _ツール

• reporter_code、flow_code、単一のperiodを指定します。aggr_levelは2（HS章、既定値）または4（項）です。partner_codeの既定値はWorld（0）です。特定の相手国に絞るには値を設定します
• 最大limit件のカテゴリーを返します（既定値は10、50を超えると取得したすべてのカテゴリーを返します）。各カテゴリーにはrank、primaryValueUsd、sharePercentが含まれます
• 取得件数が500件の上限に達した場合、truncated: trueを返します

---

comtrade_get_data_availability _ツール

• すべてのフィルターは省略可能です。reporter_code、period、freq（A／M、既定値はA）、type_code（Cは物品／Sはサービス、既定値はC）、classification（省略または空欄の場合、物品ではHS、サービスではEB10に解決されます）
• 利用可能な場合、データセットごとにtotalRecords、firstReleased、lastReleasedを返します。物品の利用可能性を確認するには、すべてのフィルターを省略します
• 年次データは通常、対象年の3～12か月後に公開されます。直近の期間を照会する前に、このツールを呼び出してください

---

comtrade_get_services_trade _ツール

• comtrade_get_trade_flowsと同じ入力を指定します。reporter_code、flow_code（M／X）、periodの値、任意のpartner_code（すべての相手国をまとめる場合は0）。最大120期間のうち、最初の12期間を処理し、残りはunservedPeriodsに一覧表示します
• service_codeを指定すると、1つのEBOPSカテゴリーに絞り込めます。comtrade_list_service_categoriesを使用してコードを確認してください
• 応答が500件の上限に達した場合、truncated: trueとtruncationHintを返します。国と期間の対象範囲は、物品よりも限定されています

---

comtrade://countries _リソース

• 国／地域の完全な一覧をapplication/json形式で返します。M49コード、ISO識別子、validAsReporter、isGroupが含まれます
• comtrade_lookup_countriesの検索対象と同じ起動時参照キャッシュから読み込まれます

---

comtrade://hs-classification/{level} _リソース

• levelのパスパラメーターには2（章）、4（項）、6（号）を指定できます。それ以外の値を指定すると、検証エラーが発生します
• 各コードのdescription、parent、isLeafを返します。すべての末端コードを列挙すると大きすぎるため、キーワード検索にはcomtrade_search_commoditiesを使用してください

機能

@cyanheads/mcp-ts-coreを基盤とし、stdioおよびStreamable HTTPトランスポート、認証方式の切り替え（none／jwt／oauth）、ストレージの切り替え（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、任意のOpenTelemetryトレース機能を備えた構造化ログに対応しています。

Comtrade 固有の機能：

• 参照データ（国コード、HS階層、EBOPSカテゴリー）は起動時にUNの静的ファイルから読み込まれます。キーワード検索でリクエストごとの取得は発生しません
• 認証済みエンドポイント（data/v1/get）と公開プレビューエンドポイント（public/v1/preview）に対応しています。サブスクリプションキーが設定されていない場合、ツールはプレビューエンドポイントにフォールバックします
• ワークフローツールでサブリクエストを並列実行します（comtrade_get_trade_balanceは輸出と輸入の取得を並行して実行します）
• 一時的な障害が発生した場合は指数バックオフで再試行し、上流からRetry-Afterヘッダーが提供されていればそれに従います
• 説明の補完 — 参照キャッシュから国名とHS／EBOPS名を結合し、プレビューエンドポイントで省略される*Descフィールドを補います

エージェント向けの出力：

• 公開プレビューの応答が500件に達した場合、復旧のヒントとともにtruncated: trueを返します
• 貿易フローのレコードにisReportedフラグを付与し、直接報告された値と、国連が推計または集計した行を区別します
• 国の検索結果にvalidAsReporterを付与し、相手国専用の地域コードを使った無効なクエリの作成を防ぎます
• 貿易収支の出力にmirrorCaveatを付与し、エラーテキストを解析せずに方法論上の注意点を示します

はじめに

公開ホスト型インスタンス

公開インスタンスは https://un-comtrade.caseyjhand.com/mcp で利用できます。インストールは不要です。キー不要の公開プレビューエンドポイント（上流リクエストあたり500レコード）で実行され、提供対象期間を少なくとも1秒間隔で間隔を空けたリクエストに分割します。Balance では期間ごとに2回のリクエストが必要なため、配列が長いほど時間がかかります。Streamable HTTP を使って、任意の MCP クライアントを接続してください。

{
  "mcpServers": {
    "un-comtrade-mcp-server": {
      "type": "streamable-http",
      "url": "https://un-comtrade.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

前提条件： UN Comtrade のサブスクリプションキーは任意です。キーがない場合、ツールは公開プレビューエンドポイント（上流リクエストあたり500レコード）を使用します。キーを設定すると認証付きアクセスが有効になります。データの取得とリクエストの上限は、UN Comtrade およびサブスクリプションの内容によって異なります。

以下を MCP クライアントの設定ファイルに追加してください。

{
  "mcpServers": {
    "un-comtrade-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/un-comtrade-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "COMTRADE_SUBSCRIPTION_KEY": "your-key-here"
      }
    }
  }
}

または、npx を使う場合（Bun は不要です）：

{
  "mcpServers": {
    "un-comtrade-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/un-comtrade-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "COMTRADE_SUBSCRIPTION_KEY": "your-key-here"
      }
    }
  }
}

または、Docker を使う場合：

{
  "mcpServers": {
    "un-comtrade-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "COMTRADE_SUBSCRIPTION_KEY=your-key-here",
        "ghcr.io/cyanheads/un-comtrade-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP を使う場合は、トランスポートを設定してサーバーを起動してください。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 COMTRADE_SUBSCRIPTION_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。開発環境と Docker イメージでは Bun 1.4.3 を使用します。
• 任意：サブスクリプションの上限に従って認証付き API アクセスを行うには、UN Comtrade のサブスクリプションキーが必要です。キーがない場合、データツールは公開プレビューエンドポイント（上流リクエストあたり500レコード）を使用します。参照／検索ツール（comtrade_lookup_countries、comtrade_search_commodities、comtrade_list_service_categories）はキーを必要とせず、静的な UN の参照ファイルを照会します。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/un-comtrade-mcp-server.git

2. ディレクトリに移動します：

cd un-comtrade-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set COMTRADE_SUBSCRIPTION_KEY if you have one

設定

すべての設定は、src/config/server-config.ts の Zod スキーマによって起動時に検証されます。

変数	説明	デフォルト
COMTRADE_SUBSCRIPTION_KEY	comtradedeveloper.un.org で取得する Azure API Management サブスクリプションキーです。キーがない場合、ツールは公開プレビューエンドポイント（上限500レコード）を使用します。	—
COMTRADE_API_BASE_URL	Comtrade API のベース URL を上書きします。	https://comtradeapi.un.org
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP エンドポイントのパスです。	/mcp
MCP_PUBLIC_URL	リバースプロキシ環境で公開オリジンを上書きします。	—
MCP_SESSION_MODE	HTTP セッションモード：auto、stateful、または stateless。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error）。	info
LOGS_DIR	ログファイル用のディレクトリ（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗したツールの引数と結果を、キー名に基づいて機密情報を伏せ字にして記録します。LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）を上限とします。自由形式の値に含まれるシークレットは伏せ字になりません。	false
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry instrumentation を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレース（/v1/traces）とメトリクス（/v1/metrics）用の OTLP ベース URL です。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	任意の OTLP ログエンドポイントです。指定した値をそのまま使用します。	—

任意の上書き設定の全一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t un-comtrade-mcp-server .
docker run --rm -e COMTRADE_SUBSCRIPTION_KEY=your-key -p 3010:3010 un-comtrade-mcp-server

Dockerfile のデフォルトは HTTP トランスポート、ステートレスセッションモードで、ログは /var/log/un-comtrade-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツールとリソースを登録し、サービスを初期化します。
src/config	環境変数の解析と、Zod による検証を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）です。参照の解決、貿易データ、ワークフローの集約に関する9つのツールがあります。
src/mcp-server/resources	リソース定義（*.resource.ts）です。国の一覧と HS 階層のリソースがあります。
src/services/comtrade-data	ComtradeDataService — リトライとキーのフォールバックに対応した、認証済み／プレビュー用リクエストビルダーです。
src/services/comtrade-reference	ComtradeReferenceService — 参照データ（国、HS、EBOPS）のローダーです。起動時のキャッシュとキーワード検索を行います。
src/services/comtrade-meta	ComtradeMetaService — データの利用可否とデータセットのメタデータを提供するエンドポイントです。
tests/	src/ に対応する単体テストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャのルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch を使用しないでください。
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使用します。
• 新しいツールとリソースは、src/mcp-server/*/definitions/index.ts のバレルを介して登録します。
• 外部 API 呼び出しは、未加工データを検証 → ドメイン型に正規化 → 出力スキーマを返す、という手順でラップします。不足しているフィールドを捏造してはいけません。
• 参照データ（国、HS コード）との結合では、リクエストごとに取得するのではなく、起動時のキャッシュからデータを取得する必要があります。

データライセンス

UN Comtrade データは、再配布条件を含む UN Comtrade ライセンス契約に従って使用してください。

貢献

Issue は歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細については LICENSE を参照してください。