unhcr-refugees-mcp-server

---

概要

UNHCR Refugee Data Finder の難民および避難に関する統計を提供します。1951 年以降の難民、庇護希望者、国内避難民、無国籍者の人口、2000 年以降の庇護申請と決定、1959 年以降の帰還と再定住が対象です。出身国および庇護国別の年間統計を取得し、大規模な結果に対して SQL を実行できます。API キーは不要です。

ツール

ツール	説明
unhcr_list_reference	国（ISO3、ISO2、UNHCR コード、名称、地域）、地域局、データセットの対象年、人口区分、庇護申請コードをデコードします
unhcr_get_population	1951年以降の出身国および／または庇護国別の年末時点の避難民ストックを取得します。UNRWA と IDMC の系列も併せて表示し、オプションで当年のナウキャストも取得できます
unhcr_get_demographics	2001年以降の人口区分、性別、年齢層別の年末時点のストックと、UNHCR が細分化できた割合を取得します
unhcr_get_asylum_applications	2000年以降の年別庇護申請件数を取得します。デフォルトでは申請段階別に分けて表示します
unhcr_get_asylum_decisions	2000年以降の年別庇護申請の決定件数を結果別に取得し、難民認定率と総保護率も表示します
unhcr_get_solutions	1959年以降の年別の難民帰還、再定住、帰化、国内避難民の帰還を取得します
unhcr_dataframe_describe	名前を指定してステージング済みデータフレームを説明するか、一覧表示が有効な場合はすべて一覧表示します。出典、期限、完全性、列スキーマも表示します
unhcr_dataframe_query	ステージング済みデータフレームに対して、読み取り専用 SQL の SELECT を1つ実行し、オプションで結果を新しいデータフレームとして保存します
unhcr_dataframe_drop	TTL の期限前にステージング済みデータフレームを削除します。オプトインが必要で、デフォルトでは tools/list に表示されません

unhcr_dataframe_drop は UNHCR_DATAFRAME_DROP_ENABLED=true の場合にのみ登録されます。他の8つのツールは常に公開されます。

データフレームのワークフロー

1. limit を超える全結果を返す unhcr_get_* の呼び出し、または stage: true を指定した呼び出しでは、すべての行を df_XXXXX_XXXXX テーブルとしてステージングし、そのハンドルを dataset で返します。
2. unhcr_dataframe_describe は、ステージング済みテーブルを列、ソースの呼び出し、期限とともに一覧表示します。HTTP で MCP_AUTH_MODE=none の場合、一覧表示は無効です。そのため、その場合は dataset にある名前を指定して各テーブルを説明します。
3. unhcr_dataframe_query は、これらのテーブルに対して読み取り専用の DuckDB SELECT を1つ実行します。register_as を指定すると、次のクエリで使う新しいテーブルとして結果を保存します。
4. テーブルは UNHCR_DATASET_TTL_SECONDS の経過後に期限切れになります（デフォルトは24時間です）。UNHCR_DATAFRAME_DROP_ENABLED=true の場合は、unhcr_dataframe_drop でそれより前に削除できます。あるテナントのステージング済み行数が1,000,000を超えると、最も古いテーブルから順に追い出され、合計を超過させた呼び出しでは、追い出されたテーブルが evicted に列挙されます。

データフレームは DuckDB のネイティブバインディング上で動作し、npm と Docker のインストールにはこれが含まれています。Claude Desktop の .mcpb バンドルには含まれていないため、そこでデータツールが返すのはインラインの結果のみです。どの環境でもデータフレームを無効にするには、CANVAS_PROVIDER_TYPE=none を設定します。

機能リファレンス

5つの unhcr_get_* ツールは共通の仕様に従います。

• スコープ： origin と asylum は、大文字小文字を区別しない ISO3 コードを文字列またはリストで受け取り、それぞれ最大50件まで指定できます。ISO2 コードは ISO3 に変換されます。UNHCR 独自のコードと国名は拒否されます。リストに指定した各コードは個別の行を返し、省略されたディメンションは、expand（origin、asylum、both）ですべての国を指定しない限り、1行に合算されます。year_from と year_to のデフォルトはデータセットの対象期間で、その期間内に制限されます。
• 行： 全結果は sort_by で並べ替えられた後、limit（デフォルトは100）までに切り詰められます。1から1,000,000までのリクエストを受け付けます。500を超える値は500に制限され、結果が空または少数の場合も、リクエストされた上限と実際に適用された上限が開示されます。データフレームが有効な場合、より大きな結果の全件がステージングされ、収まる結果でも stage: true を指定するとステージングされます。
• 出力： total_rows、complete（UNHCR_MAX_ROWS によって取得が停止された場合は false）、measure（stock または flow）、applied_scope、latest_year、ステージング時の dataset、data_notes、attribution。
• エラー： unknown_country_code、invalid_year_window、year_out_of_coverage、conflicting_scope、および再試行可能な upstream_busy。upstream_busy には retryAfter が含まれます。

---

unhcr_list_reference _ツール

• topic：countries、regions、coverage、population_types、asylum_codesのいずれかです。countriesの場合、name_containsは、指定したすべての単語を名前に含む国、またはISO3、ISO2、UNHCRコードのいずれかが指定値と一致する国を抽出します。あいまい検索は行いません
• coverageには、各データセットのfirst_year、latest_year、measureと、現在のnowcastの月が含まれます
• 国、地域、対象範囲のデータはライブAPIから取得され、24時間キャッシュされます。人口タイプと庇護コードは静的データです。UNHCRの方法論で定義されていない庇護コードには、documented: falseが付与されます

---

unhcr_get_population _ツール

• 年末時点のストックとしてrefugees、asylum_seekers、oip、idps、stateless、ooc、hstがあり、年間のフローとしてreturned_refugeesとreturned_idpsがあります。sort_byにはこれらのいずれか、またはyearを指定できます
• unrwa_refugees（UNRWAに登録されたパレスチナ難民）とidmc_conflict_idps（IDMCによる紛争起因のIDP推計値）は、その系列に値がある場合、行に併記されます。これらがUNHCRの集計値に加算されることはありません。該当するUNHCRのfootnotesも最大20件返され、footnotes_totalに総数が示されます
• include_nowcast: trueを指定すると、庇護国別の難民および庇護希望者について、UNHCRによる当年の月次推計値が追加されます。originにコードが指定されている場合は省略されます

---

unhcr_get_demographics _ツール

• population_typesはREF、ASY、OIP、IDP、STA、OOC、HST、RET、RDPに絞り込みます。sort_byにはyearまたはtotalを指定できます
• 各行は1つの人口タイプを表し、total、14の性別×年齢区分（female_0_4 … female_60_plus、female_unknown_age、female_totalと、それぞれに対応するmale_*）、disaggregated、sex_disaggregated_share（0～1）が含まれます。UNHCRに内訳がない場合、各区分はnullになります
• 合計値は別のコレクションから取得されるため、unhcr_get_populationの値と一致しない場合があります。該当するfootnotesも同様に返されます

---

unhcr_get_asylum_applications _ツール

• split_byには、authority、stage、decision_levelのうち、別々の行として保持する項目を指定します（デフォルトは["stage"]です。[]を指定すると、年、対象範囲、単位ごとの合計が1行になります）。stagesは合算前に絞り込みます。たとえば、新規申請の場合は["N"]を指定します。sort_byにはyearまたはappliedを指定できます
• 各行には、合算対象のauthorities、stages、decision_levelsの各コード、unit（personsまたはcases）、appliedが含まれます。件数が人数に加算されることはありません

---

unhcr_get_asylum_decisions _ツール

• split_byには、authorityとdecision_levelのうち、別々の行として保持する項目を指定します（デフォルトは[]で、UNHCRの率の算出方法と同様にすべて合算されます）。decision_levelsは合算前に絞り込みます。たとえば、第一審の場合は["FI"]を指定します
• 各行には、recognized、complementary_protection、rejected、otherwise_closed、total_decisions、substantive_decisions、unitに加え、実質審査決定数に対する割合としてのrefugee_recognition_rateとtotal_protection_rate（パーセント）が含まれます。分母が0またはnullの場合、率はnullになります
• sort_byにはyearまたは件数（total_decisions、substantive_decisions、recognized、rejected）を指定できます。率による並べ替えはできません

---

unhcr_get_solutions _ツール

• フローはreturned_refugees、resettlement、naturalisation、returned_idpsです。sort_byにはこれらのいずれか、またはyearを指定できます。人口データと同様に、該当するfootnotesも返されます
• 庇護国の意味は列ごとに異なります。難民の帰還元の国、再定住先の国、帰化を認めた国をそれぞれ指します。IDPの帰還は、出身国自体に記録されます

unhcr_dataframe_describe _tool

• name（df_XXXXX_XXXXX）は任意です。省略すると、ステージングされたすべてのテーブルが新しい順に一覧表示されます。HTTP で MCP_AUTH_MODE=none の場合、一覧表示は無効になり、name が必須です
• 各エントリーには、source_tool、query_params、created_at、expires_at、row_count、complete、incomplete_sources、providers、column_schema が含まれます。保存された派生テーブルは、元のテーブルが期限切れになった後や削除された後も、元の不完全なソースのハンドルを保持します。ステージングされたテーブルには、インラインの行では省略される origin_unhcr_region、origin_unsd_region、asylum_unhcr_region、asylum_unsd_region 列が追加されます

---

unhcr_dataframe_query _tool

• sql には、最大 20,000 文字の DuckDB の SELECT を 1 つ指定します。結合、集計、ウィンドウ関数、CTE を使用できます。書き込み、DDL、PRAGMA、ATTACH、ファイル参照、外部データ関数、エンジンのイントロスペクション（current_setting、current_schema、current_schemas、in_search_path）、動的なテーブル検索（query_table）、システムカタログは、理由を示す型付きエラーで拒否されます。query() が受け付けるのは単一の SQL 文字列リテラルのみで、同じゲートによる検証が行われます
• row_limit（1～10,000、デフォルトは 1,000）でクエリが実体化する行数の上限を設定し、結果が上限に達した場合は row_count_capped で示します。preview はインラインで返す行数を減らします。register_as は結果を新しい df_XXXXX_XXXXX 名で保存し、新しい TTL を設定します。これは 1,000,000 行のステージング予算に算入され、結果だけでこの上限を超える場合、register_as_too_large エラーになります
• SUM と COUNT の値は文字列（BIGINT）として返されます。attribution は、SQL が読み取るすべてのテーブルのサードパーティの系列情報を示します
• preview は 0～1,000,000 を受け付け、row_limit に合わせて上限調整されます。要求値と適用値も示されます。0 の場合もプレビュー行は返されません。complete と incomplete_sources は表示上の切り詰めとは独立して上流のカバレッジを示します。元のソースが不完全な場合、集計、結合、保存された派生テーブルも不完全なままです
• 両方の応答形式と通知を含むシリアライズ済みのツール結果は、65,536 UTF-8 バイト以内に収まります。行全体またはサイズの大きすぎるメタデータは一律に省略され、値が途中で切り詰められることはありません。result_chunks は、実体化された列、行、結果メタデータのテナント単位のスナップショットを示します。通常の TTL が適用され、ステージング予算を共有します。result_storage_unavailable は、そのスナップショットを保持できなかったことを意味します。保存された register_as テーブルは引き続き利用できます

df_ABCDE_12345 のような result_chunks.name の場合は、呼び出しごとにチャンクを 1 つ読み取ります。

SELECT chunk_index,chunk FROM df_ABCDE_12345 WHERE chunk_index=0

result_chunks.chunk_count - 1 までインデックスを増やします。各チャンクを個別に Base64 デコードし（ソースバイト数は最大 6,144）、デコードしたバイトをインデックス順に連結してから、UTF-8 としてデコードし、JSON を解析します。バイト境界で Unicode 文字が分割されることがあるため、バイトを結合してから UTF-8 をデコードしてください。スナップショットには、preview で非表示になった行を含め、row_limit まで実体化された行が含まれます。row_count_capped は、条件に一致する追加の行が実体化されなかったことを引き続き示します。登録済みの全結果を取得するには、registered_as に対してクエリを実行してください。小さなスカラー結果は Markdown テーブルで返されます。正確な空白、制御文字、ネストされた構造、または Markdown 構文を保持する必要がある値は、フェンス付き JSON で返されます

---

unhcr_dataframe_drop _tool

• name（df_XXXXX_XXXXX）。一致するものがない場合は dropped: false を返すため、呼び出しを繰り返しても安全です
• UNHCR_DATAFRAME_DROP_ENABLED=true の場合にのみ登録されます。それ以外の場合、テーブルごとの TTL によってステージング済みテーブルが回収されます

機能

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

UNHCR 固有の機能：

• UNHCR の Refugee Data Finder の背後にある API（api.unhcr.org/population/v1）向けの、API キー不要のクライアントです。この API は未知のパラメーターや片方だけの年の範囲指定を拒否せず無視するため、サーバーは許可リストにあるパラメーターのみを送信し、年の範囲は常に両端を指定して、国の照合を ISO3 に固定します（cf_type=ISO）
• 共有リクエストキュー：リクエスト開始を制御し（UNHCR_REQUESTS_PER_SECOND）、同時実行数は最大 2 件、429 応答後のクールダウン、同一リクエストの統合、レスポンスキャッシュ、呼び出しごとに 45 秒の実行時間上限を備えています
• 数値に対する UNHCR の解釈：ストックとフローを明示し、UNHCR の "-" はゼロではなく null として返し、ケース数を人数に加算せず、UNHCR の実質的な決定件数を分母として認定率を算出します
• UNHCR は 5 未満の件数（庇護決定件数は 10 未満）を最も近い 5 の倍数に丸めるため、少数の値は概算です
• UNHCR の数値を含むすべての結果には、「UNHCR Refugee Population Statistics Database」（CC BY 4.0）が出典として記載され、UNHCR のデータセット利用規約へのリンクが含まれます。UNRWA と IDMC の数値は、それぞれの提供元独自の系列データであり、UNHCR の API を通じて提供されます。これらが含まれる場合は attribution.providers で提供元をクレジットします。各提供元独自の条件が適用される場合があります

エージェントが扱いやすい出力：

• すべてのデータ結果に出典情報を付与します。applied_scope には実際に送信されたコード、年の範囲、ISO2 の書き換えが反映され、latest_year、measure、complete、attribution も含まれます
• 注意事項をデータとして提供します。data_notes には各結果の読み方（ストックまたはフロー、丸め処理、null の意味）が記載され、該当する UNHCR の footnotes は rows_matched とともに返されます
• 復旧のヒントを含む型付きエラーを返します。unknown_country_code は UNHCR コードに対応する ISO3 を提示し、year_out_of_coverage はデータセットの対象期間を示し、upstream_busy は retryAfter を含みます
• 何も黙って切り詰めません。年の範囲の調整、結果が空の場合のヒント、切り詰めの情報、完全なデータ一式を格納した場所は、すべてレスポンス内の通知として返されます

はじめに

公開ホストインスタンス

公開インスタンス（https://unhcr-refugees.caseyjhand.com/mcp）を利用できます。インストールは不要です。Streamable HTTP 経由で、任意の MCP クライアントを接続します。

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

ホストインスタンスの利用者全員で、UNHCR リクエストキューと 1 つの dataframe ワークスペースを共有します。そのため、unhcr_dataframe_describe にはそこでテーブルの正確な名前を指定します。テーブル一覧の取得はできません。

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加します。

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

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

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

または Docker を使用します。

{
  "mcpServers": {
    "unhcr-refugees-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/unhcr-refugees-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 キーもアカウントも不要です。UNHCR の API は API キー不要で、以下の変数はすべて任意です。

インストール

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

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

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

cd unhcr-refugees-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# optional: every variable has a working default

設定

変数	説明	デフォルト
UNHCR_REQUESTS_PER_SECOND	プロセス全体での、1秒あたりの上流リクエスト開始数（1～10）。HTTP インスタンスのすべての呼び出し元で共有されます。	4
UNHCR_MAX_ROWS	1回のツール呼び出しで取得する上流データの最大行数（10,000～500,000）。結果が上限を超える場合は上限で打ち切られ、complete: false が返されます。	150000
UNHCR_CACHE_MAX_MB	レスポンスキャッシュの上限（MB）。0 にすると無効になります。参照データ（国、地域、対象範囲、脚注）には独自のキャッシュがあり、常に有効です。	64
UNHCR_DATASET_TTL_SECONDS	ステージングされたデータフレームの有効期間（秒）。最小値は60です。	86400
UNHCR_DATAFRAME_DROP_ENABLED	true に設定すると、unhcr_dataframe_drop が登録されます。	false
CANVAS_PROVIDER_TYPE	データフレームエンジン：duckdb、またはデータフレームを無効にする場合は 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
  bun run test:live  # Opt-in: re-checks the upstream behaviors the client relies on against api.unhcr.org
  

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイント：サーバーの指示、ツールの登録、サービスのセットアップ。
src/config	サーバー固有の環境変数の解析と、Zod による検証。
src/mcp-server/tools/definitions	ツール定義（*.tool.ts）と、unhcr_dataframe_drop の登録を制御する登録リスト。
src/mcp-server/tools/shared	データツール間で共有されるスコープ入力、出力スキーマ、結果の整形、Markdown のレンダリング。
src/services/unhcr	UNHCR API クライアント — リクエストの構築、間隔を調整したフェッチ、レスポンスキャッシュ、参照データ、正規化、庇護申請の集計、脚注の照合。
src/services/canvas-bridge	フレームワークの DataCanvas へのアダプター — データフレームの命名、データの出所、有効期限、読み取り専用 SQL の制御。
tests/	src/ の構成に対応するユニットテストと、tests/live/ にあるオプトイン方式のライブテストスイート。

開発ガイド

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

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

貢献

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

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License のもとでライセンスされています。詳細は LICENSE ファイルを参照してください。

データの所有者は UNHCR であり、CC BY 4.0 および UNHCR のデータセット利用規約に基づいて公開されています。このプロジェクトは UNHCR から独立しており、UNHCR の承認を受けていません。