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.2

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.2
File Size Uploaded Provenance Actions
cfpb_complaints_analysis-0.1.2.tar.gz 17.2 kB With provenance Details for cfpb_complaints_analysis-0.1.2.tar.gz

Built distribution (wheel)

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

Total release size: 33.9 kB

Release files / cfpb_complaints_analysis-0.1.2.tar.gz

Download URL cfpb_complaints_analysis-0.1.2.tar.gz
Size 17.2 kB
Tags Source
SHA-256 checksum
How to use checksums
4cc7ee0bfb9295069294d73e490dd65ad312df1f0cba5cc7fc4400a03b971203
BLAKE2b-256 checksum
How to use checksums
195905d2d02dd3699da18c761e4a25ec991fc34d3cf3d22d0df6f68d507b2387
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.2-py3-none-any.whl

Download URL cfpb_complaints_analysis-0.1.2-py3-none-any.whl
Size 16.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4fa2075c689511705376238b13c07602243b6083da6d98f4f014d1f08cb988c8
BLAKE2b-256 checksum
How to use checksums
c86c219bf678cc58bc1ac81fccd01283d0ffcc3a9e763f3c86d14d7506fba100
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.2

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.2.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