worldbank-mcp-server

---

概要

世界銀行のオープンデータ：29,500 件以上の開発指標、貧困と不平等の推計値、世界銀行の融資プロジェクトを利用できます。指標を検索し、各国の時系列データを照会し、貧困指標を取得し、進行中および過去のプロジェクトを検索できます。API キーは不要です。

ツール

ツール	説明
worldbank_list_topics	世界銀行の 21 のテーマ別トピックを説明付きで一覧表示します
worldbank_list_sources	70 件以上の世界銀行データソース（データセット）をページネーション付きで一覧表示します
worldbank_list_countries	ISO コード、地域、所得水準、融資区分、座標とともに、国と地域集計を一覧表示します。地域、所得水準、融資区分で絞り込めます
worldbank_get_country	ISO2、ISO3、または集計コードで指定した国または集計単位のメタデータをすべて取得します
worldbank_search_indicators	キーワード、トピック、またはソースで 29,500 件以上の指標カタログを検索します
worldbank_get_indicator	単一指標の名称、説明、ソース、単位、トピックなどのメタデータをすべて取得します
worldbank_get_data	1 か国以上について、期間範囲、直近 N 期間、または各国の最新の空でない値 N 件を、年次、四半期、月次で照会します
worldbank_get_poverty	貧困・不平等プラットフォームから、各国と PIP の地域別、所得グループ別、融資グループ別、脆弱性グループ別の集計値について、任意の貧困ラインでの貧困者比率、貧困ギャップ、貧困の深刻度に加え、ジニ係数と十分位別シェアを取得します
worldbank_search_projects	テキスト、国、地域、ステータス、融資枠、理事会承認日で世界銀行の融資ポートフォリオを検索します

リソース

リソース	説明
worldbank://indicator/{indicatorId}	ID による指標のメタデータ — 名前、説明、出典、単位、トピック
worldbank://country/{countryCode}	ISO2、ISO3、または集計コードによる国のメタデータ — 地域、所得水準、首都、座標

機能リファレンス

worldbank_list_topics _ツール

• 入力は不要です — 21 のテーマ別トピックからなる固定分類体系全体を返します
• トピック ID（例：1 は農業、3 は経済と成長）は、worldbank_search_indicators の topic_id に指定します

---

worldbank_list_sources _ツール

• 70 以上の World Bank データソース（データセット）のページ分けされた一覧です。1 ページあたり最大 100 件です
• 各項目には ID、名前、短縮コード、最終更新日、データ／メタデータの利用可能状況が含まれます
• ソース ID（例：World Development Indicators の 2）は、worldbank_search_indicators の source_id に指定します

---

worldbank_list_countries _ツール

• 地域コード（EAS、SSF、…および AFE、EUU、LDC などの加盟グループ）、所得水準（LIC、LMC、UMC、HIC）、融資区分（IDX、IBD、IDB、LNX）でフィルターできます。条件は AND で組み合わされ、1 ページあたり最大 150 件（約 50 KB）です
• ISO コード、地域、所得水準、融資区分、首都、座標を返します。無効な地域コードまたは所得コードを指定すると、型付きエラー invalid_filter が返されます
• デフォルトでは個々の国のみが対象です。include_aggregates=true を指定すると、地域別、所得グループ別、および世界全体の集計が追加され、isAggregate で示されます

---

worldbank_get_country _ツール

• ISO2（US）、ISO3（USA）、または World Bank の集計コード（EAS、HIC、WLD）を 1 つ受け付けます。all またはリストを指定すると、multiple_countries エラーが返されます
• 地域、所得水準、融資区分、首都、座標を返します
• 復旧のヒントとして worldbank_list_countries を示す、型付きエラー country_not_found が返されます

---

worldbank_search_indicators _ツール

• query、topic_id、source_id のうち少なくとも 1 つが必要です。各キーワード語句は、順序を問わず、指標 ID、名前、または説明に一致する必要があります。1 ページあたり最大 100 件です
• 完全一致する ID／名前、語句で始まる名前、より緩やかな一致、説明のみの一致の順にランク付けされます。各ランク内では World Development Indicators の系列が先頭になり、系列本体はその内訳より先に表示されます（SP.DYN.LE00.IN が SP.DYN.LE00.FE.IN より先）
• 各指標 ID は 1 回だけ表示され、説明の先頭 150 文字が含まれます。全文は worldbank_get_indicator で取得できます

---

worldbank_get_indicator _ツール

• 呼び出しごとに指標 ID を 1 つ指定します。使用できる文字は英字、数字、.、_、- です。all、リスト、その他の文字を指定すると拒否されます
• 説明、単位、ソースデータセット、ソース組織、トピックを返します。説明内の HTML 改行は保持され、その他のマークアップは除去されます
• worldbank_search_indicators を示す、型付きエラー indicator_not_found が返されます

worldbank_get_data _ツール

• countries は ISO2、ISO3、集計コード、WLD、または単独の all を指定します。date_range（年、四半期、月、または同じ形式の期間範囲）、mrv（各国をまたいだ直近 N 期間）、mrnev（各国それぞれの直近 N 件の値）のうち、指定できるのは最大 1 つです。たとえば、エリトリアの GDP per capita は 2011 年の値で、mrv では 2025 年の値が返され、値は null になります。frequency（annual、quarterly、monthly）は、複数の形式で公開されている系列の期間形式を選択します（ケニアの CPTOTSAXN で monthly、mrv: 3 を指定すると、2026M07～M05 が返されます）。1 ページあたり最大 200 件（約 50 KB）
• 各行には両方の国コード、isAggregate、欠損値を示す value: null が含まれます。各ページには nullCount と、データの基準時点を示すソースの lastUpdated も含まれます。date_range、mrv、mrnev を指定した読み取りでは、別のクエリでキャッシュされた回答がないか確認してから再読み込みを 1 回行います。2 回失敗した場合は結果を返さず、upstream_inconsistent エラーになります
• 標準エンドポイントで提供されない指標（WDI Database Archives、PEFA、ICP、GDLD、International Debt Statistics: DSSI、Food Prices for Nutrition）は、それぞれ独自のデータセットから取得されます。適用されたリリース、分類、セクター、または相手地域は sourceScoped（dimension_value）に開示されます

---

worldbank_get_poverty _ツール

• ISO3 または ISO2 コードで経済圏を指定します。PIP がモデル推計値のみを公開している経済圏（AFG）や、PIP の集計値も指定できます。集計値には、世界（WLD）、地域（SSF、AFE）、所得グループ（LMIC／LMC）、融資グループ（IDX、IDB、IBD、REST）、脆弱性グループ（FCVY、FCVN）があります。WDI の FCS は、同じ構成員であるとは断定せず、FCVY を案内するエラーとして拒否されます。year には年、all、または MRV を指定します。poverty_line は任意で、既定では適用される PPP 基準年の国際貧困ラインになります。1 ページあたり最大 70 件の推計値（約 50 KB）
• 世帯調査の行には、貧困率、貧困ギャップ、貧困の深刻度、Watts 指数のほか、ジニ係数、平均対数偏差、分極化、十分位別シェアが含まれます。estimationType は世帯調査の行と、ギャップ補完された行を区別します。後者の不平等指標は null になり、isAggregate は集計行を示します
• fill_gaps（既定値は true）を指定すると、ギャップ補完された年が含まれます。welfare_type と reporting_level で経済圏の結果を絞り込み、ppp_version で PPP 基準年を選択します

---

worldbank_search_projects _ツール

• フリーテキストの query は、countries（ISO3、ISO2、または 3A などの世界銀行地域コード）、region、status、financial_type、理事会承認期間（approved_from／approved_to）と AND 条件で組み合わせられます。1 ページあたり最大 80 件のプロジェクトが、承認日の新しい順に返されます
• ID、名称、国、地域、ステータス、日付、IBRD・IDA・助成金の内訳を含むコミットメント額、融資枠、セクター、URL を返します。countryCodes は他のツールでも使用できます。不正なコードや解析できないクエリは、型付きの invalid_country_code／invalid_query エラーになります。結果がない場合は、結果がなくなったフィルターが示されます
• include_abstract（既定ではオフ）を指定すると、要約が追加されます。この場合、1 ページあたり 8 件となり、各要約は 5,000 文字で切り詰められます

---

worldbank://indicator/{indicatorId} _リソース

• 指標のメタデータを application/json 形式で返します。内容は名称、説明、単位、ソースデータセット、ソース組織、トピックです
• indicatorId は worldbank_search_indicators から取得します。不明な ID の場合は、復旧方法のヒントを含む型付きの not-found エラーが返されます。上流の停止やタイムアウトは、不正な ID として扱われず、独自の分類が維持されます

---

worldbank://country/{countryCode} _リソース

• 国または集計値のメタデータを application/json 形式で返します。内容は ISO コード、地域、所得水準、首都、座標です
• ISO2、ISO3、または世界銀行の集計コードを 1 つ指定できます。all やリストは拒否されます。不明なコードの場合は、上流の一時的な障害とは区別された型付きの not-found エラーが返されます

特徴

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

World Bank 固有の機能：

• 3 つの個別の上流 API（Indicators API、Poverty and Inequality Platform、Projects lending portfolio）にわたる、World Bank Open Data の全データを網羅しています
• 29,500 以上の指標について、200 か国以上と地域別集計の 60 年以上（PIP は 1963 年から）の開発データを提供します
• 上流の searchterm パラメーターでは絞り込めないため、指標カタログをクライアント側でキーワード検索します
• null の観測値や nullCount を黙って削除せず、明示します
• 国とデータの各行に isAggregate フラグを付与し、個別の国と集計エンティティを区別します

エージェントに使いやすい出力：

• ツール間の相互参照を説明に組み込んでいます。たとえば、worldbank_search_indicators はトピック ID の取得に worldbank_list_topics を、worldbank_get_data は指標の検索に worldbank_search_indicators を案内します
• すべてのツールで、型付きの reason コードと実行可能な recovery ヒントを含む、構造化されたエラー契約を提供します
• すべてのリスト／検索／データツールでページネーションメタデータ（totalCount、currentPage、totalPages）を統一しています。要求が最終ページを超えた場合は、存在するページを示す通知を返します

はじめに

公開ホストインスタンス

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

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

セルフホスト／ローカル

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

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

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

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

または、Docker を使用する場合：

{
  "mcpServers": {
    "worldbank-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/worldbank-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 ≥24.0.0）。
• API キーは不要です。World Bank Open Data API は公開されており、認証も不要です。

インストール

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

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

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

cd worldbank-mcp-server

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

bun install

4. 環境を設定します（任意）：

cp .env.example .env
# edit .env and set optional overrides

設定

すべての設定は、起動時にsrc/config/server-config.ts内のZodスキーマによって検証されます。環境変数は次のとおりです。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdioまたはhttp	stdio
MCP_HTTP_PORT	HTTP サーバーのポート	3010
MCP_HTTP_HOST	HTTP サーバーのホスト名	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	MCP サーバーをマウントする HTTP エンドポイントのパス	/mcp
MCP_PUBLIC_URL	TLS 終端リバースプロキシ環境向けのパブリックオリジンの上書き値	なし
MCP_AUTH_MODE	認証方式：none、jwt、またはoauth	none
MCP_SESSION_MODE	HTTP セッションの処理方式：stateful、stateless、またはauto。サーバーはコード内でstatelessを宣言しており、セッションごとの状態を保持しません。ここで設定した値はその宣言を上書きします	stateless
MCP_LOG_LEVEL	ログレベル（debug、info、notice、warning、error）	info
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 を有効にします	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	オプトイン形式の OTLP ログエクスポート（例：http://localhost:4318/v1/logs）。ベースのOTEL_EXPORTER_OTLP_ENDPOINTを設定しても有効にはなりません	なし
WORLDBANK_API_BASE_URL	World Bank Indicators API のベース URL の上書き値	https://api.worldbank.org/v2
WORLDBANK_PIP_BASE_URL	Poverty and Inequality Platform API のベース URL の上書き値	https://api.worldbank.org/pip/v1
WORLDBANK_PROJECTS_BASE_URL	Projects API のベース URL の上書き値	https://search.worldbank.org/api/v3
WORLDBANK_DEFAULT_PER_PAGE	リスト／検索／データ操作のデフォルトページサイズ。worldbank_get_data、worldbank_list_countries、worldbank_search_projects、worldbank_get_povertyでは、それぞれ独自のページ上限が適用されます	50
WORLDBANK_CATALOG_CACHE_TTL_MS	プロセス内参照キャッシュの有効期間。キーワードのみの検索で使用される指標カタログ、isAggregateで使用される国インデックス、ソース別の国コードと貧困関連の ISO2 コード、各ソース別データセットの概念／国／期間／ディメンション一覧、ppp_versionで使用される PIP のバージョン一覧、集計コードで使用される地域テーブル、モデル推計のみの経済圏で使用される経済圏一覧が対象です。0にするとすべて無効になります	3600000

オプションの上書き設定の全一覧は.env.exampleを参照してください。

サーバーの実行

ローカル開発

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

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

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

  bun run devcheck  # Lint, format, typecheck, and more
  bun run test      # Runs the test suite
  

Docker

docker build -t worldbank-mcp-server .
docker run --rm -p 3010:3010 worldbank-mcp-server

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

プロジェクト構成

ディレクトリ	用途
src/mcp-server/tools	ツール定義（*.tool.ts）。トピック、ソース、国、指標、データ、貧困、プロジェクトを扱う9つのツールがあります。
src/mcp-server/resources	リソース定義。指標と国のメタデータリソースがあります。
src/services/worldbank	World Bank Indicators API のサービスレイヤー。API クライアントとドメイン型を含みます。
src/services/pip	Poverty and Inequality Platform API のサービスレイヤー。独立したクライアントとドメイン型を含みます。
src/services/projects	Projects API のサービスレイヤー。独立したクライアントとドメイン型を含みます。
src/config	サーバー固有の環境変数の解析と、Zod による検証を行います。
tests/	単体テストと統合テスト。src/の構成に対応しています。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークがキャッチします。ツールのロジックではtry/catchを使用しません
• ログにはctx.log、ストレージにはctx.stateを使用します
• 新しいツールとリソースは、createApp()の配列に登録します
• 外部 API 呼び出しはラップします。生データを検証し、ドメイン型に正規化してから、出力スキーマを返します。不足しているフィールドを捏造してはいけません

コントリビューション

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

bun run devcheck
bun run test

ライセンス

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