cfpb-complaints-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| CFPB_DATA_DIR | No | Set this to use a folder you built yourself instead of downloading the Parquet data files (default cache location is ~/.cache/cfpb-complaints-analysis). | |
| CFPB_DATA_URL | No | Set this to fetch the Parquet data files (about 700 MB) from somewhere other than the default hosted service on first run. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Data: CFPB Consumer Complaint Database (complaints received 2011-12-01 onward, structured fields as CFPB publishes them) plus consumer narratives from CFPB's FOIA Reading Room archive. CFPB stopped publishing narratives in September 2026: narratives exist only for complaints CFPB had published with a narrative through 2026-08-14 (3.85M of them, none before 2015), so a complaint with no narrative may be newer, may lack consumer consent, or may be pre-2015. Complaints are unverified consumer allegations, and a company's count is not adjusted for its size. Narratives have personal data masked as XXXX by CFPB.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| dataset_infoA | What this dataset is: row counts, date ranges, narrative coverage, and the narrative freeze. Call first when unsure about coverage. |
| list_valuesA | List the values of a field with complaint counts, to find exact product/issue/response names. field is one of: product, sub_product, issue, sub_issue, company_response, company_public_response, submitted_via, state, timely_response. Optional search narrows by substring; product narrows issues to that product. Filters: company (exact name as in find_company), company_contains (substring), product, sub_product, issue, product: CFPB renamed credit reporting twice, so it appears under three product names (use list_values field=product), company_response (exact CFPB value, case-insensitive), submitted_via, state (2 letters), tag (e.g. 'Servicemember', 'Older American'), timely (true/false), date_from/date_to (YYYY-MM-DD or YYYY-MM, on date received). |
| find_companyA | Find companies by name. CFPB lists the same firm under variants and subsidiaries (e.g. 'EQUIFAX, INC.', 'Equifax Information Services LLC'), so this returns every matching name with complaint counts and first/last dates; pass the exact names you want to other tools via company, or use company_contains for all variants at once. |
| complaint_countsA | Count complaints, optionally grouped. group_by is one or two of: year, quarter, month, product, sub_product, issue, sub_issue, company, state, company_response, company_public_response, submitted_via, timely_response. Returns complaints, timely_rate, monetary_relief_rate, nonmonetary_relief_rate, in_progress_rate per group (rates are fractions of that group's complaints). Counts are raw complaint counts, not adjusted for company size. In progress and Untimely response are CFPB response categories, not outcomes. Filters: company (exact name as in find_company), company_contains (substring), product, sub_product, issue, product: CFPB renamed credit reporting twice, so it appears under three product names (use list_values field=product), company_response (exact CFPB value, case-insensitive), submitted_via, state (2 letters), tag (e.g. 'Servicemember', 'Older American'), timely (true/false), date_from/date_to (YYYY-MM-DD or YYYY-MM, on date received). |
| trendA | Complaints over time (month, quarter or year), for one filter set. Set period to month, quarter or year. The latest period is partial. In progress and Untimely response are CFPB response categories, not outcomes. Filters: company (exact name as in find_company), company_contains (substring), product, sub_product, issue, product: CFPB renamed credit reporting twice, so it appears under three product names (use list_values field=product), company_response (exact CFPB value, case-insensitive), submitted_via, state (2 letters), tag (e.g. 'Servicemember', 'Older American'), timely (true/false), date_from/date_to (YYYY-MM-DD or YYYY-MM, on date received). |
| company_profileB | Profile of one company (or all name variants via company_contains): totals, first/last complaint, top products, issues, states, response outcomes, yearly counts. Counts are not adjusted for company size. Optional date_from/date_to/product. |
| compare_companiesA | Side-by-side comparison of up to 6 companies on the same filters: complaints, timely_rate, relief rates, top product and top issue each. Each entry in companies is matched as a substring on the company name (all variants combined). Counts are not adjusted for company size. |
| search_narrativesA | Keyword search over archived complaint narratives (frozen at 2026-08-14; CFPB stopped publishing them in September 2026). query: words that must all appear (case-insensitive), or use phrase for an exact phrase, or any_of for alternatives. Returns a snippet per complaint plus its structured fields, newest first (date order, not relevance-ranked: every result contains all your words); use get_complaint for the full text. Searches scan text, so narrow with date_from/date_to, company/company_contains, product or state when you can: an unfiltered search over all years can time out. Filters: company, company_contains, product, state (2 letters), date_from/date_to (YYYY-MM-DD or YYYY-MM), plus issue, sub_product, company_response, timely, tag (these are slower). |
| count_narrativesA | Count how many archived narratives match a keyword search, optionally grouped by year, month, product, company, issue or state. Same search and filter arguments as search_narratives (without the slower issue/response filters). Use this for 'how many complaints mention X'. Counts only complaints that have a narrative (through 2026-08-14), not all complaints. Narrow with date, company or product when you can. |
| get_complaintA | One complaint by its CFPB Complaint ID: all structured fields and, when archived, the full narrative. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 10 tools
Each tool has a recognizable niche: discovery (dataset_info, list_values, find_company), search (search_narratives, count_narratives), aggregation (complaint_counts, trend, company_profile, compare_companies), and retrieval (get_complaint). The main overlap is trend versus complaint_counts with group_by=month/quarter/year, and company_profile versus complaint_counts grouped by company; descriptions hint at the distinction but an agent could easily pick the wrong one.
All names are snake_case and readable, but the convention is mixed: verb-first (list_values, find_company, search_narratives, get_complaint, compare_companies, count_narratives) alongside noun-first (dataset_info, complaint_counts, trend, company_profile). Consistent casing keeps it predictable, but the verb/noun pattern is not uniform.
Ten tools is well matched to a dataset-query server: discovery, aggregation, search, and lookup each get a few focused tools with no filler. Nothing feels redundant enough to cut, and nothing important is squeezed into one overloaded tool.
The surface covers discovery, filtering vocabulary, aggregates, trends, company comparison, narrative search, and single-record lookup, which is a full lifecycle for this dataset. The notable gap is a way to page through raw complaint records by structured filters alone (search_narratives requires keywords and only covers narrated complaints), so browsing non-narrative complaints row-by-row is not possible.