fdic-banks-mcp-server

---

概要

FDIC BankFind Suite API を利用して、営業中、合併済み、または破綻したすべての FDIC 保険対象銀行および貯蓄金融機関を検索できます。1984 年までさかのぼる四半期ごとのコールレポートの財務情報を確認し、銀行を同業他社と比較して順位付けし、多数の銀行を一度にスクリーニングし、1934 年以降の破綻情報を検索し、支店預金と市場シェアを把握できます。信用組合は NCUA の保険対象であり、対象に含まれません。API キーは不要です。

ツール

ツール	説明
fdic_search_institutions	名称、CERT、所在地、規模、認可区分、または持株会社で金融機関を検索します。他のすべてのツールで使用するCERTを返します
fdic_get_institution_financials	1つの金融機関の四半期ごとのCall Report履歴を、最新のものから順にプロフィールとともに返します
fdic_compare_peers	1つの四半期について、金融機関1行を同業グループと比較します。指標ごとに、同業中央値、四分位数、範囲、パーセンタイル、順位を返します
fdic_query_financials	CERT、州、資産範囲、指標のしきい値で絞り込んだ、複数の銀行・四半期にまたがるCall Reportのパネルデータを返します
fdic_search_failures	1934年以降の銀行破綻および支援取引を、合計、手法別の小計、任意のグループ分けとともに返します
fdic_get_deposits	Summary of Deposits：金融機関の支店と州別市場シェア、または預金額で順位付けした市場とHHIを返します
fdic_list_reference	指標カタログ、認可区分、破綻処理方法、保険基金、同業資産区分、データセットの対象範囲を返します
fdic_dataframe_describe	ステージングされたデータフレームを一覧表示するか、名前を指定して1つのデータフレームの出所、列、単位を説明します
fdic_dataframe_query	ステージングされたデータフレーム全体に対し、読み取り専用のDuckDB SELECTを1つ実行します
fdic_dataframe_drop	TTLの期限前にステージングされたデータフレームを削除します。FDIC_DATAFRAME_DROP_ENABLED=trueの場合を除き無効です

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

1. fdic_query_financialsとfdic_get_depositsはインラインプレビューを返します。結果全体がlimitを超える場合は、df_XXXXX_XXXXXというテーブルとしてステージングし、その名前をdatasetフィールドに記載します。
2. その名前をfdic_dataframe_describeに渡すと、テーブルの列、単位、基準を確認できます。
3. fdic_dataframe_queryでクエリを実行します。ステージングされたすべてのテーブルを対象に、結合、集計、ウィンドウ関数、CTEを使用できます。register_asを指定すると、結果を新しいテーブルとして保存します。
4. テーブルはFDIC_DATASET_TTL_SECONDSの期間（デフォルトは24時間）が経過すると失効します。稼働中のテーブルは合計で1,000,000行を保持し、上限を超えると最も古いものから削除されます。

ステージングはDuckDB上で実行され、デフォルトで有効です。CANVAS_PROVIDER_TYPE=noneを設定すると無効になります。Claude Desktopの.mcpbバンドルにはDuckDBのネイティブバインディングが含まれていないため、その環境ではデータフレームツールがインストール方法を案内し、それ以外のすべてのツールは通常どおり動作します。

機能リファレンス

fdic_search_institutions _ツール

• フィルター：name（最大100文字。すべての単語が現在の名称、旧称、または商号に一致する必要があります）、certs（最初の50件の一意な値）、state、city、bank_classes、min_assets / max_assets（米ドル、千ドル単位）、holding_company_rssd
• statusはactive、inactive、anyのいずれかです。nameまたはcertsが指定された場合のデフォルトはany、それ以外ではactiveです。status_filterには適用された値が表示されます
• 1ページあたり最大100件（デフォルトは20件）で、offset / next_offsetを使用してページ分割します。各レコードにはactive、合併または破綻した銀行のsuccessor_cert、holding_company.rssd、matched_onが含まれます。該当するレコードがないCERTはmissing_certsに含まれます

---

fdic_get_institution_financials _ツール

• certは必須です。metricsは最大25件（デフォルトは15指標の健全性セット）を指定できます。quartersは1～10,000を受け付け、最大200四半期を照会します（デフォルトは8四半期）。from_date / to_dateは2025-03-31、20250331、2025Q1の形式で指定できます
• 行は最新のものから順に並び、各行には指標から数値へのvaluesマップが含まれます。報告されていない値はnullです。metric_definitionsには各指標のFDICフィールド、単位、基準が記載されます
• quarters_availableは期間内にある四半期数を示します。存在しないCERTを指定するとcert_not_foundエラーになります

---

fdic_compare_peers _tool

• cert は必須です。report_date の既定値は最新の公開済み四半期（report_date_defaulted）です。metrics は最大 20 件です
• ピアグループ：peer_asset_band（既定値は same。any、under_100m、100m_1b、1b_10b、10b_250b、over_250b）に加えて、任意で peer_state を指定するか、peer_certs（先頭から一意な 200 件）を指定します。peer_certs はバンドまたは州と併用できません（conflicting_peer_filters）
• 各比較では、指標を報告した peer_count_with_value 件のピアについて、value、peer_median、peer_p25 / peer_p75、peer_min / peer_max、percentile、および rank_of の順位である rank が返されます。peer_cohort_incomplete は、ピアグループの一部のみが処理されたことを示します

---

fdic_query_financials _tool

• フィルター：最大 100 件の certs、state、min_assets / max_assets、最大 5 件の metric_filters（min および／または max を指定した metric）、および最大 30 件の metrics。from_date / to_date の既定値は最新の公開済み四半期です
• インラインの limit は既定で 50 です。sort_by / sort_order で並べ替えます。より大きなパネルはデータフレームとして全件がステージングされます
• パネルの上限は FDIC_PANEL_MAX_ROWS（既定値は 50,000）で、新しい四半期が優先されます。total_matching、rows_fetched、panel_truncated で除外されたデータを確認できます

---

fdic_search_failures _tool

• フィルター：name、certs（先頭から一意な 50 件。1977 年より前の事象にはありません）、state、from_date / to_date（YYYY-MM-DD）、methods、min_assets。resolution の既定値は failure で、assistance または all も指定できます
• summary は一致するすべての事象を集計し、by_method で内訳を示します。group_by（year、state、method、insurance_fund）を指定すると groups` が追加されます
• total_assets_missing_count、total_deposits_missing_count、estimated_loss_missing_count は未報告の金額の件数を示します。一致する記録済み金額がない場合、合計値は null です。日付、損失額、資産額で sort できます。1 ページあたり最大 200 件（既定値は 25 件）です

---

fdic_get_deposits _tool

• cert のみを指定すると、金融機関の支店と各州における預金シェアが返されます（mode: "institution"）。地理情報（state、county、city、zip、msa_code）を指定すると、その市場のすべての金融機関が hhi とともに順位付けされます（market）。両方を指定すると institution_in_market になります。county と city には state が必要です
• 1994 年以降の year を指定できます。既定値は最新の調査年（year_defaulted）です。預金額は 6 月 30 日時点の国内支店預金額で、単位は米ドルの千ドルです
• インラインの limit は既定で 25 です。件数がそれより多い場合はデータフレームとしてステージングされ、全件数は total_rows で確認できます

---

fdic_list_reference _tool

• 1 回の呼び出しにつき topic は 1 つです：metrics、bank_classes、failure_methods、insurance_funds、peer_asset_bands、または coverage
• metrics は 49 個すべての指標名について、FDIC フィールド、単位、基準、注意事項、in_default_set を一覧表示します。組み込みテーブルから提供され、FDIC へのリクエストは発生しません

---

fdic_dataframe_describe _tool

• name（dataset フィールドの df_XXXXX_XXXXX）を指定すると、そのテーブルのソースツール、パラメーター、行数、有効期限、column_schema、column_units が返されます
• name を指定しない場合は、現在有効なテーブルを新しい順に 1 ページあたり 50 件一覧表示します。offset / next_offset でページを移動します。HTTP で MCP_AUTH_MODE=none の場合、一覧表示は無効になり、listing_unavailable として失敗します
• データフレームのステージングが無効の場合、canvas_unavailable として失敗します

---

fdic_dataframe_query _tool

• 1 回の呼び出しにつき SELECT は 1 つで、最大 20,000 文字です。書き込み、DDL、ファイル読み取り関数、システムカタログへのアクセスは、型付きの理由（non_select_statement、denied_function、system_catalog_access など）で拒否されます
• row_limit は 1～1,000,000 を受け付け（既定値は 1,000）、実行される行数は最大 10,000 です。より多くの行が一致した場合は row_count_capped で示されます。preview でインラインの行数を設定します
• register_as を指定すると結果が新しいデータフレームとして保存されます。1,000,000 行を超える場合は register_as_too_large として失敗します。COUNT(*) などの BIGINT の結果は文字列として返されます

---

fdic_dataframe_drop _ツール

• ステージング済みデータフレームのnameを指定します。削除された場合はdropped: trueを返し、その名前のデータフレームがステージングされていない場合はdropped: falseを返します
• FDIC_DATAFRAME_DROP_ENABLED=trueでない限り無効です。それ以外の場合、テーブルはTTLに従って期限切れになります

機能

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

FDIC固有の機能：

• 4つのBankFindデータセットを読み取ります。すべての被保険認可金融機関（営業中・廃業済み）、1984年以降の四半期ごとのCall Report財務データ、1934年以降の破綻および支援取引、1994年以降の年次Summary of Depositsです
• リクエストをペース制御します（FDIC_RATE_LIMIT_RPS、同時実行は最大4件）。レスポンスキャッシュとFDICから429が返された後のクールダウンを備えています。各呼び出しの制限時間は45秒（パネルの場合は55秒）です
• FDICフィールドコード、単位、基準を含む、厳選された49種類のCall Report指標カタログを提供します。_ytd指標は1月1日から累積し、接尾辞のない収益・リターン指標は単一四半期を対象とします
• BankFind特有の仕様に対応しています。大文字と小文字を区別するコード値、文字列型の報告日、データなしを示す値、銀行が報告しなかった比率が0として報告される仕様などです
• 配列入力は順序を保ったまま重複を除去し、最大1,000項目に制限します。空のcerts、peer_certs、bank_classes、methodsは拒否されます

エージェントに適した出力：

• すべてのデータレスポンスにdata_as_of、metric_definitions、およびサーバーが期間を選択した場合のreport_date_defaulted／year_defaultedが含まれます
• 未報告の指標はnullとして返され、値は補完されません
• 次に呼び出すツール名を含む復旧情報付きの型付きエラー（cert_not_found、conflicting_peer_filters、no_report_for_period）を返します。レート制限エラー（pacer_shed、upstream_rate_limited）にはretryAfterが含まれます
• processed_certs／deferred_certsおよびprocessed_metrics／deferred_metricsにより、照会済みの項目と新しい呼び出しで渡す項目を区別します

はじめに

公開ホストインスタンス

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

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

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

セルフホスト／ローカル

以下をMCPクライアントの設定ファイルに追加してください。APIキーは不要です。

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

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

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

または、Dockerを使用します：

{
  "mcpServers": {
    "fdic-banks-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/fdic-banks-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キーは不要です。FDIC BankFind Suite APIは公開されています。

インストール

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

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

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

cd fdic-banks-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# every variable is optional; edit .env to override a default

設定

変数	説明	デフォルト
FDIC_RATE_LIMIT_RPS	api.fdic.gov へのリクエスト開始数の上限（毎秒、1～15）。プロセス内のすべての呼び出し元で共有されます。	8
FDIC_CACHE_TTL_SECONDS	プロセス内の FDIC レスポンスキャッシュの有効期間（秒）。0 にするとキャッシュが無効になります。	3600
FDIC_PANEL_MAX_ROWS	1 つの fdic_query_financials パネルの行数上限（1,000～200,000）。上限に達した場合は新しい四半期のデータが保持されます。	50000
FDIC_DATASET_TTL_SECONDS	ステージングされた各データフレームの有効期間（秒、最小 60）。	86400
FDIC_DATAFRAME_DROP_ENABLED	true に設定すると、fdic_dataframe_drop が有効になります。	false
CANVAS_PROVIDER_TYPE	データフレームエンジン：duckdb、またはステージングとデータフレームツールを無効にする場合は none。未設定の場合、サーバーは duckdb を設定します。	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() のエントリーポイントです。ツールを登録し、サーバーの指示を設定して、FDIC サービスとキャンバスブリッジを起動します。
src/config	Zod を使用した、サーバー固有の環境変数の解析と検証を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）、共有入力スキーマ、Markdown ヘルパーです。ツールは 10 個あります。
src/services/fdic	FDIC BankFind クライアント（リクエストペーサー、レスポンスキャッシュ、クエリビルダー、正規化）、指標カタログ、参照テーブルです。
src/services/canvas-bridge	フレームワークの DataCanvas 用アダプターです。df_<id> 形式のテーブル名、テーブルごとの TTL、データの来歴を扱います。
tests/	src/ の構成に対応した単体テストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、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 ファイルを参照してください。