ilostat-mcp-server

---

概要

ILOSTATは、国際労働機関のデータベースで、労働統計を提供しています。指標を検索し、国、地域、所得グループの観測値を取得して、地域間で比較し、労働市場のプロフィールを作成できます。すべての値には、報告値、モデル推計値、予測値のいずれかが明示されます。APIキーは不要です。

ツール

ツール	説明
ilostat_search_indicators	平易な言葉での用語とフィルターを使って指標カタログを検索します。各検索結果には、利用可能な頻度ごとのデータセット ID が表示されます
ilostat_describe_indicator	1 つのデータセットについて、定義、単位と倍率、使用中の内訳コード、対象地域、値の分類方法を説明します
ilostat_query_indicator	地域または地域グループ、性別、内訳コード、出典、期間で絞り込み、1 回の呼び出しで最大 3 つのデータセットの観測値を取得します
ilostat_get_country_profile	1 つの地域の主要な労働市場統計を、最新の報告値と最新の ILO モデル推計値を並べて表示します
ilostat_compare_geographies	1 つのデータセットの 1 つのスライスについて、共通期間または最新期間の地域を順位付けし、任意で N 年間の変化も表示します
ilostat_list_reference	ILOSTAT のコード体系を解読します。地域、地域グループ、データベース、主題、性別、内訳、出典、ステータスフラグ、注記が対象です
ilostat_dataframe_describe	ステージングされた df_<id> データフレームを名前で説明するか、すべて一覧表示します（認証方式が none の HTTP では無効）。由来、対象範囲、基準数、列スキーマを表示します
ilostat_dataframe_query	ステージングされたデータフレームに対して読み取り専用の SQL SELECT を 1 つ実行し、任意で結果を新しいデータフレームとして保存します
ilostat_dataframe_drop	TTL が切れる前に、ステージングされたデータフレームを削除します

ilostat_dataframe_drop は ILOSTAT_DATAFRAME_DROP_ENABLED=true でない限り無効です。また、CANVAS_PROVIDER_TYPE=none にすると、3 つすべてのデータフレームツールが無効になります。

機能リファレンス

ilostat_search_indicators _ツール

• 平易な言葉での query（すべての用語が単語または単語の接頭辞に一致する必要があり、大文字・小文字、アクセント、labour／labor の違いは同一視されます）に加え、frequency、database、subject、breakdown、measure、aggregates_only の各フィルターを指定できます。フィルターで検索する場合は query を省略します
• 1 ページあたり最大 50 件（デフォルトは 10 件。limit に 50 より大きい値を指定すると 50 件に適用され、その旨が通知されます）。next_cursor で次のページに進みます。各検索結果には、頻度ごとの dataset_id、対象年、n_ref_area、last_update、has_aggregates が含まれます。facets には一致する全項目の件数が表示されます
• 認識されない database、subject、breakdown、measure のコードを指定すると、unknown_filter_code エラーになります

---

ilostat_describe_indicator _ツール

• 1 つの dataset_id（UNE_DEAP_SEX_AGE_RT_A）、または頻度を問わずすべてを説明する指標コードを指定します。認識されないコードの場合は、found: false と guidance が返されます
• 定義、unit とその multiplier、頻度のバリエーション、breakdowns（性別コード、および合計が is_total としてマークされた classif1／classif2 コード）、default_slice、対象となる ref_areas、basis_rule、最初の 20 件の related_datasets と related_total が含まれます
• SDMX API が応答できない場合、structure_status は unavailable となり、エラーにはならず、内訳、単位、地域が返されません

---

ilostat_query_indicator _ツール

• dataset_ids は最大 100 件まで指定できます。最初の異なるデータセット 3 件が照会され、残りは次の呼び出し用に remaining_dataset_ids として返されます。ref_areas（最大 300 件）および／または area_group、sex、classif1、classif2、sources、期間で絞り込みます。期間は、特定の time、年の範囲を指定する time_from／time_to、latest_only、またはその両方で指定できます
• latest_only を指定すると、各系列で独自の最新期間が使われます。全期間のデータが 1 回の呼び出しで読み取るには大きすぎる場合、地域とデータセットごとの最新期間に切り替わり、applied_filters.latest_mode と通知にその旨が示されます
• source_selection はデフォルトで best です。all または secondary も指定できます。行には source、obs_status、notes、basis が含まれ、これらは legend で解読されます。applied_filters には送信されたすべてのパラメーターが反映されます
• インラインプレビューの上限を超える結果は、df_<id> の dataframe として全件ステージングされます。ILOSTAT_MAX_ROWS を超えるリクエストは、フィルターなしの場合は request_too_broad、フィルターありの場合は result_too_large で失敗します

---

ilostat_get_country_profile _tool

• 年次データを含む1つの ref_area。ISO3 国コード（KEN）または X コードの集計値（X01：世界、地域、所得グループ）と、sex（デフォルトは SEX_T、または SEX_M、SEX_F）
• 9つの主要指標（労働力率、就業者・人口比率、失業、若年失業、若年層の就学・就業・職業訓練のいずれにも参加していない状態（NEET）、インフォーマル雇用、就業、労働所得分配率、ワーキングプア）。各指標について、その区分での最新の reported 値と、それとは別に、最新の非予測 modelled 推計値を含みます
• reported 値がない場合は欠損のままとなり、reported_missing に記載されます。集計値には modelled 値のみが含まれます

---

ilostat_compare_geographies _tool

• 1つの dataset_id と1つの区分（sex、classif1、classif2。デフォルトはデータセットの合計値）。対象地域は ref_areas（最大300件）、area_group、またはその両方で指定し、少なくとも1つは必須です
• period を指定すると、すべての地域で同じ期間の値を取得します。指定しない場合は、include_projections が有効でない限り予測値を除外し、各地域の lookback_years（デフォルトは10年）以内の最新値を取得します。change_years（1～30年）を指定すると、その期間における各値の変化も追加されます
• 変化には、比較元の値の source、basis、status、notes が引き継がれ、source_changed、basis_changed、break_in_series のフラグが付きます。通知には、同条件で比較できない変化の件数が含まれます
• 各行には rank、value、period、basis、source が含まれます。値がない地域は reason とともに missing に格納され、comparability には mixed_periods、basis_counts、distinct_sources が示されます

---

ilostat_list_reference _tool

• topic：ref_areas、area_groups、databases、subjects、sexes、classifications、classification_types、sources、obs_status、notes、frequencies
• テキストの filter、または最大100件の完全一致する codes を指定します（見つからないコードは not_found に記載されます。area_groups を完全一致で検索すると、加盟国の一覧が表示されます）。ref_area を指定すると sources が絞り込まれ、classification_type を指定すると classifications が絞り込まれます
• 1ページあたり最大500件（デフォルトは50件。より大きな limit は500件として適用され、その旨の通知が表示されます）。next_cursor を使用して続きのページを取得します

---

ilostat_dataframe_describe _tool

• 1つの df_XXXXX_XXXXX を渡すか、name を省略してステージング済みデータフレームをすべて新しい順に一覧表示します（認証方式が none の HTTP では一覧表示は無効です。正確な名前を使用してください）
• 各項目には、生成元の source_tool とその query_params、datasets、coverage、basis_counts、attribution、created_at／expires_at、row_count、SQL の実行に使う column_schema が含まれます
• 各データセットでは、単位の完全な情報が unit のほかに保持されます：unit_measure、unit_type、unit_type_label、unit_multiplier、unit_multiplier_label。値が再スケーリングされることはありません

---

ilostat_dataframe_query _tool

• df_<id> テーブルに対して、DuckDB の SELECT 文を1つ実行します（結合、集計、ウィンドウ関数、CTE に対応）。最大20,000文字です。書き込み、DDL、複数文の SQL、ファイル参照とファイル読み取り関数、エンジン設定の読み取り、システムカタログは拒否されます
• row_limit はマテリアライズされる行数の上限です（デフォルトは1,000件。1回の呼び出しにつき最大10,000件に制限され、上限に達すると row_count_capped フラグが設定されます）。preview はインラインで返される行数を指定し、ILOSTAT_PREVIEW_CHARS に達した場合も停止します。applied_limits には適用された値が示され、BIGINT 値は文字列として返されます
• register_as を指定すると、結果全体を新しいデータフレームとして保存し、新しい TTL が設定されます。結果が1,000,000行を超える場合は register_as_too_large として失敗し、容量を確保するために削除された古いデータフレームは evicted に記載されます

---

ilostat_dataframe_drop _tool

• name で指定したステージング済みデータフレームを、TTL の期限前に1つ削除します。冪等で、該当するものがない場合は dropped: false となります
• ILOSTAT_DATAFRAME_DROP_ENABLED=true かつデータフレームが有効な場合にのみ一覧表示されます。破壊的操作を行う唯一のツールです

特徴

@cyanheads/mcp-ts-core を基盤としており、stdio と Streamable HTTP のトランスポート、プラグイン可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログを提供します。

ILOSTAT 固有の機能：

• キー不要の ILO API を 2 つ使用します。ILOSTAT データ API はカタログ、コード辞書、観測値を提供し、ILO SDMX API は各データセットの内訳コード、デフォルトのスライス、単位を提供します
• カタログとコード辞書はメモリに保持され、ILOSTAT_CATALOG_REFRESH_HOURS ごとに再確認されます。ツールが受け取るすべてのコードは、上流へのリクエスト前にこれらの情報と照合して検証されます
• 上流ホストごとにリクエストペーサーを設けています。429 またはチャレンジページが発生すると、再試行可能な upstream_busy として retryAfter とともに呼び出し元に返されます。最大 5,000 行のデータレスポンスは、ILOSTAT_CACHE_TTL_SECONDS の期間キャッシュされます
• データフレームはデフォルトで有効です。ILOSTAT_PREVIEW_CHARS を超えるクエリや比較は、DuckDB の df_<id> テーブルとして全件ステージングされ、ILOSTAT_DATASET_TTL_SECONDS の期間保持されます。テナントごとに最大 1,000,000 行、100 個のデータフレームを保持でき、古いものは削除されて evicted に名前が記録されます。CANVAS_PROVIDER_TYPE=none の場合、または .mcpb バンドル内（DuckDB バインディングなし）の場合、結果はインラインプレビューまでとなり、その旨が示されます
• ILOSTAT のデータとメタデータは、CC BY 4.0 の ILO オープンアクセス方針に基づいて公開されています。すべてのデータレスポンスには、数値とともに保持すべき attribution が含まれます

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

• すべての値に根拠を付与します。各行は reported、modelled_estimate、projection のいずれかで、結果には basis_counts が含まれます。国別プロファイルでは報告値とモデル値を別々のフィールドで返し、一方の値で他方を補完することはありません
• 出所とデコード情報：行には source、obs_status、注記コードが保持され、それらを解読する legend が付属します。クエリと比較のレスポンスには、デフォルト値を含む applied_filters が返されます
• 該当なしもデータとして扱います。不明なデータセットは guidance とともに found: false を返し、値のない比較対象地域は型付きの reason とともに missing に格納されます
• 型付きエラー：失敗時には理由（unknown_code、request_too_broad、upstream_busy、…）と復旧のヒントが含まれます

はじめに

公開ホストインスタンス

公開インスタンスを https://ilostat.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP を介して、任意の MCP クライアントから接続してください。

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

ホストインスタンスのすべての呼び出し元で、ILO API ごとのリクエストペーサーと 1 つのデータフレームワークスペースを共有するため、ilostat_dataframe_describe ではテーブルの正確な名前を指定します。一覧表示は無効です。

セルフホスト／ローカル

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

{
  "mcpServers": {
    "ilostat-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/ilostat-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "ilostat-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/ilostat-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または Docker を使用します。

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

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動します。

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

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• API キーやアカウントは不要です。どちらの ILO API も公開されています。

インストール

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

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

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

cd ilostat-mcp-server

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

bun install

4. 環境を設定します。

cp .env.example .env
# every variable is optional; see Configuration below

設定

変数	説明	デフォルト
ILOSTAT_CATALOG_REFRESH_HOURS	カタログの更新を確認する間隔（時間単位、1～168）。	6
ILOSTAT_MAX_ROWS	1 回のクエリで返す、またはステージングする行数の上限（1,000～1,000,000）。	500000
ILOSTAT_PREVIEW_CHARS	インラインプレビューの予算（シリアライズ後の文字数、1,000 以上）。これを超える結果はデータフレームとしてステージングされます。	40000
ILOSTAT_CACHE_TTL_SECONDS	最大 5,000 行の上流データレスポンスをキャッシュする秒数。0 にするとキャッシュが無効になります。	900
ILOSTAT_DATASET_TTL_SECONDS	ステージングされたデータフレームのテーブルごとの TTL（秒単位、60 以上）。	86400
ILOSTAT_DATAFRAME_DROP_ENABLED	true に設定すると、ilostat_dataframe_drop が公開されます。	false
CANVAS_PROVIDER_TYPE	ステージングされたデータフレームの DataCanvas エンジン：duckdb、またはデータフレームと 3 つのデータフレームツールを無効にする場合は none。	duckdb
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry を有効にします。	false

省略可能なオーバーライドの一覧は、.env.example を参照してください。

サーバーの実行

ローカル開発

• 本番バージョンをビルドして実行する：

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

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

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。デフォルトでデータフレームを有効にし、ツールを登録して、カタログの読み込みを開始します。
src/config	サーバー固有の環境変数の解析と、Zod による検証を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）と、それらで共有する入力およびレンダリング用ヘルパーです。ツールは 9 個あります。
src/services/rplumber、src/services/sdmx	src/services/upstream の間隔制御と再試行に対応した HTTP レイヤーを使用する、ILOSTAT データ API および ILO SDMX API 用のクライアントです。
src/services/catalog	インメモリのカタログスナップショット、指標の検索、参照リスト、ページングを扱います。
src/services/structure	指標ごとの SDMX 構造と単位をキャッシュします。
src/services/observations	リクエストの検証、サイズの事前チェック、行のデコード、比較、レスポンスのキャッシュを行います。
src/services/profile	国の概要プロフィールを扱います。
src/services/basis	各値を報告値、モデル推計値、または予測値に分類するルールです。
src/services/canvas-bridge	DataCanvas アダプター：df_<id> のステージング、来歴、SQL、削除を扱います。
tests/	上流の記録済みフィクスチャを使い、src/ に対応した Vitest テストスイートです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックでは try/catch を使いません
• ログには ctx.log を、ストレージには ctx.state を使用します
• 新しいツールは src/mcp-server/tools/definitions/index.ts の buildToolDefinitions() に登録します
• 外部 API の呼び出しは、ラップしてから、未加工データを検証 → ドメイン型に正規化 → 出力スキーマを返す、という順に処理します。不足しているフィールドを捏造してはいけません

コントリビューション

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

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License の下でライセンスされています。詳細は LICENSE ファイルを参照してください。ツールが返す ILOSTAT データは International Labour Organization に帰属し、CC BY 4.0 の下で公開されています。ILOSTAT とデータセット ID を引用してください。