CFPB consumer complaints

io.github.bnovariniv0.1.3更新於 Oct 8, 2026

CFPB consumer complaints: 18M records, 3.85M archived narratives. Search, counts, trends.

已驗證Streamable HTTP可網頁執行Data & AnalyticsFinance

概覽

AI 產生的概覽

讓助理查詢 1820 萬筆 CFPB 消費者申訴與 385 萬筆封存敘述，用於計數、趨勢、公司概況與關鍵字檢索。

功能
以 Parquet 資料形式提供 CFPB 消費者申訴資料庫，並透過 MCP 伺服器供助理查詢。工具包括 dataset_info、list_values、find_company、complaint_counts、trend、company_profile、compare_companies、search_narratives、count_narratives 與 get_complaint。可依公司、產品與日期統計及觀察申訴趨勢、比較公司，並對消費者敘述做關鍵字檢索。
適用情境
適合消費者金融研究：某家銀行或貸款機構的申訴量與趨勢、公司之間的比較，以及尋找提到透支費等主題的敘述。以日期、公司或產品篩選時效果最好，因為未篩選的敘述檢索很慢。
執行需求
提供遠端端點，未宣告需要驗證。本機方式為以 pip 安裝的 Python 套件，以 stdio 指令啟動；首次執行會下載約 700 MB 的 Parquet 檔案到快取目錄。選用變數 CFPB_DATA_URL 與 CFPB_DATA_DIR 可變更資料來源或讀取目錄。
安裝前請注意
申訴是未經查證的消費者指控，計數為原始資料、未依公司規模調整，最近幾個月資料不完整，敘述涵蓋至 2026-08-14 且 2015 年前沒有。同一家公司可能以多個名稱出現。未篩選的敘述檢索約需十秒，跨所有年份的計數需 30 到 45 秒。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 CFPB consumer complaints，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable，透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

{
  "mcpServers": {
    "cfpb-complaints-analysis": {
      "type": "http",
      "url": "https://cfpb-complaints-analysis.fly.dev/mcp"
    }
  }
}

README

cfpb-complaints-analysis

The CFPB Consumer Complaint Database as clean Parquet, plus an MCP server so an AI assistant can query it: 18.2 million complaints (2011 to today) and 3.85 million consumer narratives.

What is in it

LayerSourceCoverage
Structured complaintsCFPB's public complaint file, files.consumerfinance.gov/ccdb/complaints.csv.zip18,239,728 complaints, received 2011-12-01 to 2026-10-07 (rebuild to refresh)
NarrativesCFPB FOIA Reading Room, "CFPB Consumer Complaint Database Narratives Archive"3,851,415 narratives, published through 2026-08-14, none before 2015

Both are CFPB's own files. Nothing comes from a third party. CFPB describes the narratives as public domain for FOIA purposes, and says on its data page that complaint data is "freely available for anyone to use, analyze, and build on."

The narrative freeze

CFPB stopped publishing complaint narratives in September 2026 (database release 24, and the Aug 14, 2026 announcement that it would cease discretionary publication of narratives and visualizations). It moved the previously published narratives to its FOIA Reading Room. The live complaint file has no narrative column any more.

This project joins the archived narratives back to the live complaints by Complaint ID. So:

  • Narratives exist only for complaints CFPB had published with one through 2026-08-14. Complaints from after that have none, and it will stay that way.
  • Fewer than half of complaints ever had a narrative: the consumer had to consent, and none were published before 2015.
  • The archive thins out near the end: about 17,000 narratives each for May and June 2026, about 10,000 for July, and 1 for August. This is in CFPB's source files, so 2026 narrative counts are not comparable to earlier months.
  • Narratives are scrubbed by CFPB (personal data shows as XXXX).
  • Structured fields keep updating when you rebuild from CFPB's live file.

Use it

pip install cfpb-complaints-analysiscfpb-complaints-mcp

The first run downloads the Parquet files (about 700 MB) from the hosted service to ~/.cache/cfpb-complaints-analysis. Set CFPB_DATA_URL to fetch them from somewhere else, or CFPB_DATA_DIR to use a folder you built yourself. Add the server to your MCP client as a stdio command, or use the hosted endpoint listed in the MCP registry as io.github.bnovarini/cfpb-complaints-analysis.

Tools: dataset_info, list_values, find_company, complaint_counts, trend, company_profile, compare_companies, search_narratives, count_narratives, get_complaint.

Example questions: What do people complain about at Navy Federal versus PenFed? How did mortgage complaints about Rocket change by year? Find 2024 narratives that mention "overdraft fee" at a credit union.

Build it yourself from CFPB's sources: cfpb-complaints --data data build.

Read this before quoting numbers

  • Complaints are unverified consumer allegations. CFPB says so itself.
  • Counts are raw. A large company will have more complaints than a small one; nothing is scaled by customers or accounts.
  • CFPB lists some firms under several names. Use find_company and company_contains to include all variants.
  • The newest months are partial: complaints are still being sent to companies, and "In progress" is a status, not an outcome.
  • Keyword narrative search scans text. Unfiltered searches take about ten seconds, and counts across all years can take 30 to 45 seconds. A date, company or product filter makes them much faster.

Checks

Every count is reconciled to CFPB's own published numbers. See docs/AUDIT.md, including the figures that do not match and why.

License

MIT for the code. The data is CFPB's.

來源：README.md，提交 79c73df

工具

0
工具後設資料尚未被收錄。

版本歷史

1
  1. v0.1.3最新Oct 8, 2026