Skip to main content

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

Layer Source Coverage
Structured complaints CFPB's public complaint file, files.consumerfinance.gov/ccdb/complaints.csv.zip 18,239,728 complaints, received 2011-12-01 to 2026-10-07 (rebuild to refresh)
Narratives CFPB 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-analysis
cfpb-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.

Metadata

Release files for cfpb-complaints-analysis 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cfpb-complaints-analysis 0.1.3
File Size Uploaded Provenance Actions
cfpb_complaints_analysis-0.1.3.tar.gz 17.5 kB With provenance Details for cfpb_complaints_analysis-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cfpb-complaints-analysis 0.1.3
File Interpreter ABI Platform Actions
cfpb_complaints_analysis-0.1.3-py3-none-any.whl Python 3 none any Details for cfpb_complaints_analysis-0.1.3-py3-none-any.whl

Total release size: 34.5 kB

Release files / cfpb_complaints_analysis-0.1.3.tar.gz

Download URL cfpb_complaints_analysis-0.1.3.tar.gz
Size 17.5 kB
Tags Source
SHA-256 checksum
How to use checksums
e71d48b79a3a5fbf04f755aa2539dfc7b22b963c91cc06bb75b789d5fb350df1
BLAKE2b-256 checksum
How to use checksums
dbbe1e64a7bfefb1e224fa1d5506e6b00bbb8ee97d5965bb7ef7ecdfb40bf8b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.

Transparency log

Release files / cfpb_complaints_analysis-0.1.3-py3-none-any.whl

Download URL cfpb_complaints_analysis-0.1.3-py3-none-any.whl
Size 17.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a82f3cd02dfc3058350e9268843f59350a21b6646cae9fc658442bb292af4549
BLAKE2b-256 checksum
How to use checksums
41f70c7e32dfaea9916810745cd801cd400a43140adabe78a25524cb590e83b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.

Transparency log

Security for cfpb-complaints-analysis 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cfpb_complaints_analysis-0.1.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page