CFPB consumer complaints

cfpb-complaints-analysis

将 CFPB 消费者投诉数据库整理为干净的 Parquet 文件，并提供 MCP 服务，让 AI 助手可以查询：1820 万条投诉（从 2011 年至今）和 385 万条消费者陈述。

包含内容

层	来源	覆盖范围
结构化投诉	CFPB 的公开投诉文件，files.consumerfinance.gov/ccdb/complaints.csv.zip	18,239,728 条投诉，接收时间为 2011-12-01 至 2026-10-07（重新构建即可更新）
陈述	CFPB FOIA 阅览室，“CFPB Consumer Complaint Database Narratives Archive”	3,851,415 条陈述，发布至 2026-08-14，2015 年之前没有

两者都是 CFPB 自己的文件，不含任何第三方数据。CFPB 将这些陈述描述为 FOIA 用途下的公共领域内容，并在其数据页面上表示，投诉数据“可供任何人免费使用、分析和继续开发”。

陈述停止更新

CFPB 于 2026 年 9 月停止发布投诉陈述（数据库版本 24，以及 2026 年 8 月 14 日发布的公告：将停止自行决定发布陈述和可视化内容）。它将此前发布的陈述移至 FOIA 阅览室。实时投诉文件现在已不再包含陈述列。

本项目通过 Complaint ID 将存档的陈述关联回实时投诉。因此：

• 只有 CFPB 截至 2026-08-14 已发布陈述的投诉才有陈述。此后产生的投诉没有陈述，而且以后也不会有。
• 从未有陈述的投诉占比超过一半：消费者必须同意，且 2015 年之前没有发布过陈述。
• 存档末尾的陈述数量明显减少：2026 年 5 月和 6 月各约有 17,000 条，7 月约有 10,000 条，8 月仅有 1 条。这是 CFPB 源文件中的情况，因此 2026 年的陈述数量无法与更早月份进行比较。
• CFPB 会清理陈述中的信息（个人数据显示为 XXXX）。
• 通过 CFPB 实时文件重新构建时，结构化字段会持续更新。

使用方法

pip install cfpb-complaints-analysis
cfpb-complaints-mcp

首次运行时，会将 Parquet 文件（约 700 MB）从托管服务下载到 ~/.cache/cfpb-complaints-analysis。设置 CFPB_DATA_URL 可从其他位置获取文件；设置 CFPB_DATA_DIR 可使用自行构建的文件夹。将此服务作为 stdio 命令添加到 MCP 客户端，或使用 MCP registry 中列出的托管端点 io.github.bnovarini/cfpb-complaints-analysis。

工具：dataset_info、list_values、find_company、complaint_counts、trend、company_profile、compare_companies、search_narratives、count_narratives、get_complaint。

示例问题：人们对 Navy Federal 和 PenFed 有哪些投诉？针对 Rocket 的抵押贷款投诉数量逐年有何变化？查找 2024 年信用合作社中提及“透支费”的陈述。

根据 CFPB 的来源自行构建：cfpb-complaints --data data build。

引用数字前请阅读

• 投诉是未经核实的消费者指控。CFPB 自己也明确说明了这一点。
• 数量是原始数量。大公司的投诉会多于小公司；数据没有按客户数或账户数进行标准化。
• CFPB 会以多个名称列出某些机构。使用 find_company 和 company_contains 纳入所有变体。
• 最新月份的数据尚不完整：投诉仍在发送给相关公司，“处理中”是一种状态，不代表处理结果。
• 关键词陈述搜索会扫描文本。未筛选的搜索大约需要 10 秒，统计所有年份的数量需要 30 到 45 秒。添加日期、公司或产品筛选条件会快得多。

核查

每项数量都与 CFPB 自行公布的数据进行了核对。请参阅 docs/AUDIT.md，其中包括不匹配的数据及其原因。

许可证

代码采用 MIT 许可证。数据属于 CFPB。