mcp-nbb

mcp-nbb

National Bank of Belgium の SDMX 統計 API 用 MCP サーバーです。

221 件の NBB データフロー（194 件の BE2 + 27 件の IMF/SDDS）を、LLM に使いやすい 6 つのツールと閲覧可能な 3 つのリソースとして公開します。充実したカタログを同梱しているため、LLM は冗長な API 呼び出しを行わずにデータフローを検索、説明、照会できます。

• アップストリーム：https://nsidisseminate-stat.nbb.be/rest（NSI Web Service v8）
• トランスポート：stdio（標準 MCP）
• Python：3.11+
• プラットフォーム：Linux、macOS、Windows
• 14 のカテゴリに分類された 221 件のデータフロー：DATAFLOWS_CATALOG.md を参照

---

インストール

PyPI から（推奨）

# With uv (runs without installing globally)
uvx mcp-nbb

# Or install into a regular venv
pip install mcp-nbb

ソースから

git clone https://github.com/lacausecrypto/mcp-nbb.git
cd mcp-nbb
pip install -e .

パッケージには充実したカタログ一式（src/nbb_mcp/data/catalog/ に約 9 MB）が含まれています。通常の使用ではビルド手順は必要ありません。

---

Claude Desktop の設定

macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json、Linux では同等のファイルを編集します。

uvx を使用（PyPI で公開後に推奨）

{
  "mcpServers": {
    "nbb": {
      "command": "uvx",
      "args": ["mcp-nbb"]
    }
  }
}

ローカルの編集可能インストールから

macOS / Linux：

{
  "mcpServers": {
    "nbb": {
      "command": "/Users/you/projects/mcp-nbb/.venv/bin/mcp-nbb"
    }
  }
}

Windows：

{
  "mcpServers": {
    "nbb": {
      "command": "C:\\Users\\you\\projects\\mcp-nbb\\.venv\\Scripts\\mcp-nbb.exe"
    }
  }
}

Claude Desktop を再起動すると、6 つの nbb_* ツールが MCP パネルに表示されます。

---

ツール

ツール	API 呼び出し	目的
nbb_search(query, …)	0	ローカルにある 221 件のデータシートをあいまい検索します（en/fr/nl/de）。
nbb_describe(dataflow_id, …)	0（デフォルト）	充実したデータシートの全情報を返します（次元、コードリスト、キーのテンプレート、よく使われるクエリ）。force_refresh=True を指定するとライブで再検証します。
nbb_query(dataflow_id, key=…, filters=…)	1	汎用的なデータ取得です。key（生の SDMX）または filters（{"FREQ":"D","EXR_CURRENCY":"USD"}）を指定します。
nbb_quick(topic, …)	1	よく使われる 18 件のクエリをトピック別に手軽に呼び出します。下のトピック表を参照してください。
nbb_compare(series, …)	N	2～5 件の系列を共通の時間インデックスに揃え、より細かい頻度は終値集計でダウンサンプリングします。
nbb_status()	0	カタログ、キャッシュ、API 設定の診断スナップショットを返します。

nbb_quick のトピック

トピック	データフロー	パラメーター
exchange_rate	BE2/DF_EXR	currency、frequency
policy_rate	BE2/DF_IRESCB	—
mortgage_rate	BE2/DF_MIR	—
long_term_yield	BE2/DF_IROLOYLD	—
inflation_hicp	BE2/DF_HICP_2025	—
inflation_national	BE2/DF_NICP_2025	—
ppi	BE2/DF_PPI	—
industrial_production	BE2/DF_INDPROD	—
gdp / gdp_growth	BE2/DF_QNA_DISS	—
unemployment_rate	BE2/DF_UNEMPLOY_RATE	—
employment	BE2/DF_EMPLOY_DISS	—
government_debt	BE2/DF_CGD	—
government_deficit	BE2/DF_NFGOV_NET_DISS	—
current_account	BE2/DF_BOPBPM6	—
consumer_confidence	BE2/DF_CONSN	—
business_confidence	BE2/DF_BUSSURVM	—
trade_balance	BE2/DF_EXTERNAL_TRADE_OVERVIEW	—

リソース

URI	内容
nbb://catalog	221 件すべてのデータフローをカテゴリ別にまとめた Markdown インデックスです。
nbb://dataflow/{agency}/{dataflow_id}	1 件のデータフローの充実したデータシートです。
nbb://category/{category}	カテゴリ内のすべてのデータフローです。

---

Claude でのプロンプト例

「過去1か月の EUR/USD 為替レートを教えてください」 → nbb_quick("exchange_rate", currency="USD", frequency="D", last_n_observations=30)

「2020年以降のベルギーの GDP 成長率と失業率を比較してください」 → nbb_compare([{dataflow_id:"DF_QNA_DISS",label:"GDP"}, {dataflow_id:"DF_UNEMPLOY_RATE",label:"Unemployment"}], start_period="2020-Q1")

「消費者信用に関する NBB のデータフローを検索してください」 → nbb_search("consumer credit") → nbb_describe(...) → nbb_query(...)。

---

設定（環境変数）

すべての設定には適切なデフォルト値があります。環境変数で上書きできます。

変数	デフォルト	用途
NBB_API_BASE_URL	https://nsidisseminate-stat.nbb.be/rest	SDMX REST ベース URL
NBB_API_TIMEOUT	30	リクエストごとのタイムアウト（秒）
NBB_USER_AGENT	ブラウザーの UA	WAF に必須 — デフォルトは有効な Chrome UA 文字列です
NBB_ORIGIN	https://dataexplorer.nbb.be	WAF に必須
NBB_HTTP_CACHE_ENABLED	true	永続ディスクキャッシュ
NBB_HTTP_CACHE_PATH	OS のキャッシュディレクトリ	キャッシュの場所を上書きします（デフォルトは platformdirs.user_cache_dir）
NBB_MEMORY_CACHE_TTL_DATA	300	データレスポンスの TTL（秒）
NBB_MEMORY_CACHE_TTL_STRUCTURE	3600	構造レスポンスの TTL（秒）
NBB_RATE_LIMIT_REQUESTS	100	独自に設定するレート制限（リクエスト／期間）
NBB_RATE_LIMIT_PERIOD	60	レート制限の時間枠（秒）
NBB_RETRY_ATTEMPTS	3	一時的なエラー発生時の再試行回数
NBB_LOG_LEVEL	INFO	DEBUG／INFO／WARNING／ERROR
NBB_LOG_FORMAT	json	json または console

デフォルトのキャッシュパスは次のとおりです。

• Linux：~/.cache/mcp-nbb/
• macOS：~/Library/Caches/mcp-nbb/
• Windows：%LOCALAPPDATA%\mcp-nbb\Cache\

---

カタログの更新

同梱されている src/nbb_mcp/data/catalog/ のスナップショットは、221 個の各データフローについて DSD とコードリストを取得して再生成されます。

mcp-nbb-build-catalog --force

オプション：

• --force — 既存のファイルを無視して、すべてのフィッシュを再構築します。
• --limit N — 最初の N 個のフローのみを処理します（デバッグ用）。
• --only BE2/DF_EXR,BE2/DF_HICP_2025 — 指定したフローを再構築します。
• --concurrency 5 — DSD リクエストを並列処理します。

ライブ API を使用した全体の再構築には約80秒かかります。カタログのサイズは、各ディメンションのコードリストを200コードに切り詰めることで約9 MB以下に抑えられています（一部の IMF フローには65,000以上のコードがあります）。

毎週実行される GitHub Action（build-catalog.yml）がカタログを再構築し、差分が検出された場合は PR を作成します。

---

トラブルシューティング

「WAF が HTML リダイレクトを返しました」

NBB API は WAF の背後にあり、ブラウザーらしい User-Agent と Origin: https://dataexplorer.nbb.be ヘッダーがないリクエストには、HTML の 200 リダイレクトを返します。クライアントはデフォルトで両方を設定します。NBB_USER_AGENT を上書きする場合は、本物らしいブラウザー文字列を指定してください。

データクエリで「HTTP 404 NoResultsFound」が発生する

SDMX キーに一致する系列がありませんでした。有効なコードを確認するには nbb_describe(dataflow_id) を使用するか、すべてのデータを取得してから start_period／end_period で絞り込むには filters={} または key="all" を指定してください。

「観測値が多すぎるため、切り詰められました」

各データレスポンスは、デフォルトで max_observations=200 に制限されます。nbb_query(max_observations=1000) で上限を増やすか、期間を絞ってクエリしてください。

カタログが見つからない

同梱の src/nbb_mcp/data/catalog/ を使わずに実行する場合は、mcp-nbb-build-catalog を一度実行してカタログを生成してください。

---

開発

開発ワークフローの詳細については、CONTRIBUTING.md を参照してください。概要：

pip install -e ".[dev]"
pytest                     # full suite (unit + integration + E2E)
pytest -m "not e2e"        # fast subset
ruff check src tests
mcp-nbb-build-catalog      # refresh the bundled catalogue
mcp-nbb                    # run the server (stdio)

CI は Python 3.11 および 3.12 を使用して Linux、macOS、Windows で実行されます。分類済みの一覧については、DATAFLOWS_CATALOG.md を参照してください。

---

セキュリティ

脆弱性は非公開でご報告ください。詳細は SECURITY.md をご覧ください。

ライセンス

MIT — ライセンスの全文については LICENSE をご覧ください。

免責事項

このプロジェクトは、ベルギー国立銀行と提携関係になく、同銀行の承認も受けていません。同銀行の公開 SDMX REST API を利用する独立したクライアントです。ブラウザーのような User-Agent および Origin ヘッダーは、上流の WAF によって必要とされており、公開統計データへのアクセスのみに使用されます。NBB の利用規約を遵守する責任はユーザーにあります。