Consumer Financial Protection Bureau Complaints

This repository contains a local-only MCP server for querying the U.S. Consumer Financial Protection Bureau (CFPB) Consumer Complaint Database. The server is designed to be launched via standard input/output, making it ideal for integration with tools such as Claude Desktop.

Files

• complaints.py – Main MCP server that exposes a single tool, search_complaints, for retrieving complaint records from the CFPB API.
• pyproject.toml – Minimal project metadata and dependency declarations.
• claude_desktop_config.json – Example configuration for launching the server from Claude Desktop.

Requirements

• Python 3.11+
• uv or pip for installing dependencies

Required Python packages are listed in pyproject.toml and include httpx, mcp[cli], and python-dateutil.

Setup (optional)

uv run automatically creates a virtual environment, locks your dependencies, syncs them, and then executes the script. If you plan to launch the server with uv run complaints.py, you can skip installing requirements ahead of time.

For users who prefer to pre-install packages or use plain pip, install dependencies with uv:

uv pip install -r pyproject.toml

Or with plain pip:

pip install -r pyproject.toml

Running

To launch the server directly from the command line for a smoke test:

uv run complaints.py

The server runs over stdio only and waits for requests from an MCP-aware client (e.g., Claude Desktop).

Running tests

Execute the unit tests using Python's unittest discovery. From the repository root, run:

python -m unittest discover -s tests -v

This requires the dependencies listed in pyproject.toml to be installed.

Claude Desktop Configuration

The claude_desktop_config.json file includes an example entry pointing to the complaints.py script. Replace INSERTPATH with the path to this repository on your machine and import the configuration into Claude Desktop.

References

• CFPB Consumer Complaint Database API documentation – underlying API used by this MCP server.
• Model Context Protocol quickstart tutorial – tutorial that helped build this example.

License

This project is licensed under the MIT License.