fdic-banks-mcp-server

---

概述

通过 FDIC BankFind Suite API 查询所有 FDIC 承保的银行和储蓄机构，包括仍在营业、已合并或已倒闭的机构。查询可追溯至 1984 年的季度《银行状况报告》财务数据、对银行进行同业排名、一次性筛查多家银行、搜索 1934 年以来的倒闭记录，以及查看分支机构存款和市场份额。信用合作社由 NCUA 承保，不包含在内。无需 API 密钥。

工具

工具	描述
fdic_search_institutions	按名称、CERT、所在地、规模、特许类别或控股公司查找机构；返回其他工具所需的 CERT
fdic_get_institution_financials	单家机构的季度 Call Report 历史数据，按时间从近到远排列，并附带其简介
fdic_compare_peers	对比一家机构与某一季度的同业群体：提供每项指标的同业中位数、四分位数、范围、百分位和排名
fdic_query_financials	按 CERT、州、资产范围和指标阈值筛选多家银行、多季度的 Call Report 面板数据
fdic_search_failures	查询自 1934 年以来的银行倒闭和援助交易，提供总数、按方法分类的小计，以及可选分组
fdic_get_deposits	存款摘要：查询某机构的分行和州市场份额，或查询按存款额排名并附带 HHI 的市场
fdic_list_reference	指标目录、特许类别、倒闭方法、保险基金、同业资产区间和数据集覆盖范围
fdic_dataframe_describe	列出已暂存的数据框，或按名称描述其中一个：来源、列和单位
fdic_dataframe_query	对已暂存的数据框运行一条只读 DuckDB SELECT 语句
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 设为 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 会报告实际应用的值
• 每页最多 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 _工具

• cert 为必填项；report_date 默认为最近发布的季度（report_date_defaulted）；最多可指定 20 个 metrics
• 同行组：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）
• 每项比较都会返回 value、peer_median、peer_p25 / peer_p75、peer_min / peer_max、percentile，以及 rank_of 的 rank；统计范围为报告了该指标的 peer_count_with_value 个同行；peer_cohort_incomplete 表示同行组仅部分处理

---

fdic_query_financials _工具

• 筛选条件：最多 100 个 certs、state、min_assets / max_assets、最多 5 个 metric_filters（每项包含 metric 及 min 和/或 max），以及最多 30 个 metrics；from_date / to_date 默认为最近发布的季度
• 内联 limit 默认为 50，按 sort_by / sort_order 排序；较大的数据面板会整体暂存为 dataframe
• 数据面板上限为 FDIC_PANEL_MAX_ROWS（默认 50,000），并保留最新季度；total_matching、rows_fetched 和 panel_truncated 会报告未纳入的内容

---

fdic_search_failures _工具

• 筛选条件：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。可按日期、损失或资产排序；每页最多 200 条（默认为 25 条）

---

fdic_get_deposits _工具

• 仅提供 cert 时，返回该机构的分支机构及其在各州的存款占比（mode: "institution"）；提供地理位置（state、county、city、zip、msa_code）时，会按 hhi 对该市场中的所有机构进行排名（market）；两者同时提供时，返回 institution_in_market。county 和 city 必须同时提供 state
• year 可从 1994 年起选择，默认为最近一次调查（year_defaulted）；存款为截至 6 月 30 日的国内分支机构存款，单位为千美元
• 内联 limit 默认为 25；较大的数据集会暂存为 dataframe，total_rows 给出完整行数

---

fdic_list_reference _工具

• 每次调用只能指定一个 topic：metrics、bank_classes、failure_methods、insurance_funds、peer_asset_bands 或 coverage
• metrics 会列出全部 49 个指标名称及其 FDIC 字段、单位、统计口径、注意事项和 in_default_set；数据来自内置表格，不会向 FDIC 发出请求

---

fdic_dataframe_describe _工具

• name（取自 dataset 字段的 df_XXXXX_XXXXX）会返回该表的来源工具、参数、行数、过期时间、column_schema 和 column_units
• 不提供 name 时，会按最新优先顺序列出实时表格，每页 50 个，并使用 offset / next_offset 翻页；通过 HTTP 使用 MCP_AUTH_MODE=none 时，列表功能会被关闭，并以 listing_unavailable 失败
• dataframe 暂存功能关闭时，会以 canvas_unavailable 失败

---

fdic_dataframe_query _工具

• 每次调用执行一条 SELECT，最多 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 会将结果保存为新的 dataframe；超过 1,000,000 行时会以 register_as_too_large 失败；COUNT(*) 等 BIGINT 结果会以字符串形式返回

---

fdic_dataframe_drop _工具

• staged dataframe 的 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 专属功能：

• 读取四类 BankFind 数据集：机构（所有受保存款保险的牌照，包括活跃和非活跃牌照）、自 1984 年起的季度 Call Report 财务数据、自 1934 年起的倒闭和援助交易，以及自 1994 年起的年度 Summary of Deposits
• 对请求进行速率控制（FDIC_RATE_LIMIT_RPS，最多 4 个并行请求），并使用响应缓存；收到 FDIC 429 响应后会进入冷却期；每次调用的时间预算为 45 秒（面板为 55 秒）
• 精选的 49 项 Call Report 指标目录，包含 FDIC 字段代码、单位和口径；_ytd 指标从 1 月 1 日起累计，不带后缀的收入和回报指标则覆盖单个季度
• 处理 BankFind 的特殊情况：代码值区分大小写、报告日期为字符串类型、缺失值哨兵，以及银行未报告比率时会将其报告为 0
• 数组输入按顺序去重，最多包含 1,000 项；不接受空的 certs、peer_certs、bank_classes 和 methods

便于 Agent 使用的输出：

• 每个数据响应都包含 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 请求速率控制器和一个 dataframe 工作区，因此 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	单个 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 服务和 canvas 桥接。
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 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证授权。详情请参阅 LICENSE 文件。