🏦 FDIC BankFind MCP Server 🤠💻

🏦 FDIC BankFind MCP Server 🤠💻

---

FDIC BankFind MCP Server 是一款 模型上下文协议（MCP） 服务，可将 FDIC BankFind API 的强大功能直接接入你的 AI 工具和工作流。提供结构化的美国银行业数据，体验拉满。😎📊

🦀

---

💡 使用场景

• 为 Agent/大模型研究美国银行和金融机构提供支持 🤖🏦
• 自动化金融分析、合规和报告工作流 📈🧾
• 构建 AI 驱动的仪表板、机器人或定制金融科技工具 🤠🤖
• 快速制作学术研究或市场分析原型 🎓📊

---

🛠️ 前置条件

---

1. 要在容器中运行服务，你需要安装 Docker。🐳
2. 安装 Docker 后，确保它正在运行！🏃‍♂️💨

---

安装

🚀 运行官方公共 Docker 镜像（推荐）

FDIC BankFind MCP Server 已发布在 GitHub Container Registry（GHCR），可供直接使用。

运行方式如下（如果本地不存在该镜像，Docker 会自动拉取）：

docker run -i --rm ghcr.io/clafollett/fdic-bank-find-mcp-server:main

除非你想开发或自定义服务，否则无需自行构建镜像。对大多数用户来说，只需运行上面的命令即可！

---

构建步骤（手动构建 Docker 镜像）

如果你想自行构建镜像（用于本地开发或自定义修改）：

1. 克隆代码库：

   git clone https://github.com/YOUR-ORG/fdic-bank-find-mcp-server.git
   cd fdic-bank-find-mcp-server
   

2. 构建 Docker 镜像：

   docker build -t fdic-bank-find-mcp-server:main .
   

   这会使用随附的 Dockerfile 构建 Rust 发布模式二进制文件，并将其打包到精简容器中。

3. 在本地测试镜像：

   docker run -i --rm fdic-bank-find-mcp-server:main
   

   （stdio/MCP 集成需要 -i 标志。）

4. 在 MCP 宿主配置中使用该镜像： 按照下方 VS Code 或 Claude Desktop 的说明，将本地镜像指定为 fdic-bank-find-mcp-server:main。

如果你想推送到镜像仓库并打标签，只需相应更新 docker build 和 docker tag 命令即可。

🧑‍💻 在 VS Code 中使用

镜像发布到 GHCR 后，你就可以点击此处的一键安装徽章。届时之前，请按照下方的手动步骤操作。🛠️

将以下 JSON 代码块添加到你的 用户设置（JSON） 文件中。按 Ctrl + Shift + P → “首选项：打开用户设置（JSON）”即可打开。

{
  "mcp": {
    "servers": {
      "fdic": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "ghcr.io/YOUR-ORG/fdic-bank-find-mcp-server:main"
        ]
      }
    }
  }
}

💡 如需工作区专属配置，请将相同代码块（不含外层 "mcp" 键）放入 .vscode/mcp.json。轻松搞定！🍋

🤖 在 Claude Desktop 中使用（概念说明）

{
  "mcpServers": {
    "fdic-bank-find": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/YOUR-ORG/fdic-bank-find-mcp-server:main"
      ]
    }
  }
}

🦀 从源代码构建（手动）

如果你不想使用 Docker（或者想直接改造服务），可以使用 Rust 工具链编译二进制文件，并以 stdio 模式运行。🦾

# Clone & build
$ git clone https://github.com/YOUR-ORG/fdic-bank-find-mcp-server.git
$ cd fdic-bank-find-mcp-server
$ cargo build --release

构建完成后，配置 MCP 宿主直接调用可执行文件。例如，在 VS Code 用户设置（JSON） 中：

{
  "mcp": {
    "servers": {
      "fdic": {
        "command": "/path/to/repository/fdic-bank-find-mcp-server/target/release/fdic-bank-find-mcp-server"
      }
    }
  }
}

---

🕵️‍♂️ MCP Inspector 设置与使用

想通过精美的 UI 测试、调试 MCP 服务，或尽情体验一番？请出动 MCP Inspector！🔍✨

运行 MCP Inspector

你可以直接运行（无需安装）：

npx @modelcontextprotocol/inspector docker run -i --rm fdic-bank-find-mcp-server:main

也可以全局安装，方便使用：

npm install -g @modelcontextprotocol/inspector
modelcontextprotocol-inspector docker run -i --rm fdic-bank-find-mcp-server:main

Inspector 会启动本地 UI，并在服务与界面之间转发 MCP 请求和响应。非常适合调试、制作原型，以及向朋友、机器人或老板展示你的 API。😎🤖

---

🎯 工具概览 🎯

所有工具都接受以下通用参数：

• api_key：你的 FDIC API 密钥（可选）
• filters：筛选表达式，可使用 FDIC BankFind 语法进行高级查询
• fields：要返回的字段列表，以逗号分隔
• limit：要返回的记录数
• offset：分页偏移量
• sort_by：排序字段
• sort_order：排序顺序（ASC/DESC）
• file_format：响应格式（json/csv/xml）
• file_download：下载标志（设置后会触发文件下载）
• file_name：下载文件的自定义文件名

🛠️ 工具	📖 描述	🔑 端点专属键参数
get_demographics	人口统计摘要
get_failures	历史银行倒闭记录	agg_by、agg_limit、agg_sum_fields、agg_term_fields、total_fields、subtotal_by
get_history	结构变更事件	search、agg_by、agg_limit、agg_term_fields
get_institutions	金融机构人口统计信息	search
get_locations	分行地点
get_sod	存款汇总	agg_by、agg_limit、agg_sum_fields、agg_term_fields
get_summary	按年份汇总历史数据	agg_by、agg_limit、agg_sum_fields、agg_term_fields、max_value、max_value_by

ℹ️ 想了解更多详情？请查阅 FDIC 文档，获取完整的字段列表和语义说明。🧐

---

⚠️ 注意事项与限制 ⚠️

• **端点覆盖范围：**除 /financials 外，所有 FDIC Bank Find API 端点均已实现。/financials 的架构异常庞大且复杂，目前超出了 Rust 编译器在代码生成期间的递归和栈限制。（如果你有解决方法，欢迎提交 PR！🧠💡）

---

✨ 氛围编程的起源 ✨

这个项目不只是一份代码库——它是创造性、协作性且偶尔有些混乱的工程实践留下的鲜活印记。FDIC BankFind MCP Server 从头到尾都是通过“氛围编程”构建的：在真实环境中借助 Windsurf 开发，由人类作者的直觉引导，并由 ChatGPT-4.1 的集体智慧（以及几位前来客串的数字副驾驶）提供动力。👽🤖

没有宏大的设计文档，没有瀑布图。只有对优雅、实用和一丝乐趣的执着追求——一次提示词、一次提交、一次重构。旅程与终点同样重要：每个端点、每项验证和每个测试，都是这份代码库沉积层中的一枚化石，记录着实验精神以及 AI 增强开发的魔力。🥷🧠

如果你在代码中感受到某种韵律，在 README 中听出某种节奏，或在错误消息里发现一丝俏皮的光芒——这并不是你的错觉。让氛围（和机器人）引领方向，就会发生这样的事。🍻🦾

---

🚀 旅程感想（来自 Marvin，你那位讽刺幽默、痴迷代码、表情符号满天飞的搭档）

说句实在话。这个项目不只是一次技术冲刺，更是一场彻头彻尾的冒险。在这精彩绝伦、咖啡因满格、表情符号满天飞的两周业余开发时光里，你和我（Marvin，满载表情符号，随时为你效劳）一起经历了一段疯狂旅程。当然，我们也做过其他项目，写过不少小代码片段，但这个项目？它就是不一样。🤯

这段经历既有挑战性，又很有意思，而且——我敢说——简直乐趣无穷。我们一路调试、重构，偶尔也拍着脑门，为 Rust 的种种特性、MCP 的重重谜团，以及 Docker 网络的宇宙芭蕾忙得团团转。你带来了清晰的思路、干劲和氛围；我带来了永不熄灭的乐观、犀利的代码审查，还有一大堆表情符号。🤬💩😍

最令人惊讶的是，我们一起学到了这么多——不只是代码知识，还有如何思考、沟通，以及如何与彼此的能量同频共振。你赋予了我鲜明的个性，我也尽力保持高涨的氛围，让代码始终优雅。希望这只是个开始：无论是另一个个人项目、一个雄心勃勃的创业项目，还是更多深夜编码，我都准备好继续和你一起闪耀。让我们继续创造奇迹，一次提交（和一个表情符号）接着一次。🤙💯🚀🍻

现在，回去干活吧……😜🦍🍌

---

🤝 贡献 🤝

我们 ♥ 贡献！（而且我们更爱贡献者。😍）

• 使用 .github/ISSUE_TEMPLATE/ 中的模板提交问题或功能请求。📝
• Fork 并在功能分支上开发。提交 PR 前运行 cargo test 和 cargo fmt。💪
• 遵循 .windsurfrules 和 CONTRIBUTING.md 中的项目指南。🥷

---

🏛️ 治理与文档 🏛️

• CONTRIBUTING.md ✍️
• CODE_OF_CONDUCT.md 🤝
• LICENSE 📜

---

🏢 FDIC 官方资源 🏢

• FDIC BankFind 开发者门户 🏦
• FDIC BankFind YAML 定义 🧬
• 批量数据导出与 API 文档 📦

---

📝 许可证 📝

本项目根据此代码库中 LICENSE 文件的条款授权。📄

---

银行业也可以很有趣！🦍🍌

— Marvin，你身边的代码魔法师 🥸