# FDIC BankFind MCP Server

`fdic-mcp-server` is an MCP (Model Context Protocol) server for the [FDIC BankFind Suite API](https://api.fdic.gov/banks/docs/). It gives LLM hosts a clean way to search FDIC-insured institutions, retrieve public banking records, and run common multi-bank analysis workflows without custom FDIC API plumbing.

It is useful when you want an MCP-compatible client to answer questions about banks, failures, branches, quarterly financials, deposit data, or peer performance using a stable tool surface and machine-readable responses.

## Table Of Contents

- [Project Status](#project-status)
- [Why This Project Exists](#why-this-project-exists)
- [Documentation](#documentation)
- [Installation](#installation)
- [Usage](#usage)
- [Available Tools](#available-tools)
- [Data Notes](#data-notes)
- [Support](#support)
- [Contributing](#contributing)
- [License](#license)

## Project Status

Active development. The server is usable today and the tool surface is covered by tests, but the project is still evolving as client support and analysis workflows improve.

## Why This Project Exists

The FDIC BankFind Suite API is public and useful, but it is not packaged for MCP clients out of the box. This project solves that by:

- exposing BankFind datasets as MCP tools
- preserving both human-readable and machine-readable responses
- adding server-side analysis helpers for multi-bank comparison workflows
- supporting both local stdio hosts and remote HTTP hosts

## Documentation

Public user docs:

- [User’s Guide](https://jflamb.github.io/fdic-mcp-server/)

Repo reference docs:

- [Reference home](./reference/README.md)
- [Technical specification](./reference/specification.md)
- [Architecture](./reference/architecture.md)
- [Key decisions](./reference/decisions.md)
- [Self-hosted HTTP deployment](./reference/self-hosting.md)
- [Plans and design notes](./reference/plans/README.md)

Project and release info:

- [Release history](https://github.com/jflamb/fdic-mcp-server/releases)
- [Archived release notes](./docs/release-notes/index.md)
- [Security policy](./SECURITY.md)

## Installation

Prerequisites:

- Node.js 20 or later
- npm

Run directly without a global install:

```bash
npx fdic-mcp-server
```

Install globally:

```bash
npm install -g fdic-mcp-server
fdic-mcp-server
```

Install from GitHub Packages:

```bash
npm install -g @jflamb/fdic-mcp-server --registry=https://npm.pkg.github.com
fdic-mcp-server
```

Install from source:

```bash
git clone https://github.com/jflamb/fdic-mcp-server.git
cd fdic-mcp-server
npm install
npm run build
```

## Usage

### Hosting

The project-operated public endpoint and website chatbot are retired. Install the server locally or operate your own HTTP deployment. GitHub Pages remains the documentation site. Remote-only clients require a reachable HTTPS endpoint supplied by you or your operator.

### Run Locally

Stdio transport:

```bash
node dist/index.js
```

HTTP transport:

```bash
TRANSPORT=http PORT=3000 node dist/index.js
```

The HTTP MCP endpoint is `http://127.0.0.1:3000/mcp` by default.

Notes:

- Local HTTP runs bind to `127.0.0.1` by default. Set `HOST` if you intentionally want a different bind address.
- Browser-origin requests are checked against `ALLOWED_ORIGINS`. If unset, the server allows the local defaults for `localhost` and `127.0.0.1` on the configured port, plus non-browser requests with no `Origin` header.
- HTTP requests are stateless by default and support MCP `2026-07-28`. Each request carries its own protocol metadata; no `MCP-Session-Id` or instance affinity is required. SDK compatibility handling also serves older clients.
- `ALLOWED_HOSTS` accepts comma-separated hostnames (without schemes or ports). Defaults are `localhost`, `127.0.0.1`, and `[::1]`. Add your endpoint hostname for remote deployments; setting `HOST` alone does not authorize a hostname.
- Requests are limited to 100 KiB. Progress updates stream on the originating POST response. Standalone GET streams and DELETE session teardown are no longer supported.

See [self-hosting and migration notes](./reference/self-hosting.md) for deployment controls and SDK integration changes.

Container builds use `PORT=8080` by default for self-hosted containers.

Set `FDIC_MAX_RESPONSE_BYTES` to override the upstream FDIC response-size guard. The default is `5242880` bytes (5 MiB).

### Minimal MCP Configuration

```json
{
  "mcpServers": {
    "fdic": {
      "command": "npx",
      "args": ["-y", "fdic-mcp-server"]
    }
  }
}
```

If you are running from a local clone instead of the published package:

```json
{
  "mcpServers": {
    "fdic": {
      "command": "node",
      "args": ["/path/to/fdic-mcp-server/dist/index.js"]
    }
  }
}
```

Client-specific setup details are in [docs/clients.md](./docs/clients.md).

### Usage Examples

Find active banks in North Carolina with assets over $1 billion:

```text
filters: STNAME:"North Carolina" AND ACTIVE:1 AND ASSET:[1000000 TO *]
```

Get the 10 costliest bank failures since January 1, 2000:

```text
filters: FAILDATE:[2000-01-01 TO *]
sort_by: COST
sort_order: DESC
limit: 10
```

Compare North Carolina banks between two quarterly report dates:

```text
state: North Carolina
start_repdte: 20211231
end_repdte: 20250630
sort_by: asset_growth
sort_order: DESC
(fdic_compare_bank_snapshots)
```

Build a peer group for a specific bank:

```text
cert: 29846
repdte: 20241231
(fdic_peer_group_analysis)
```

More examples are in [docs/usage-examples.md](./docs/usage-examples.md).

## Available Tools

| Tool | Description |
|------|-------------|
| `search` | ChatGPT-compatible citation search across institutions, failures, branches, and schema docs |
| `fetch` | Fetch full citation text for a result returned by `search` |
| `fdic_search_institutions` | Search FDIC-insured banks and savings institutions |
| `fdic_get_institution` | Get details for a specific institution by CERT number |
| `fdic_search_failures` | Search failed bank records |
| `fdic_get_institution_failure` | Get failure details for a specific institution |
| `fdic_search_locations` | Search branch and office locations |
| `fdic_search_history` | Search structural change events such as mergers and name changes |
| `fdic_search_financials` | Search quarterly Call Report financial data |
| `fdic_search_summary` | Search annual financial summary data |
| `fdic_search_sod` | Search Summary of Deposits branch-level deposit data |
| `fdic_search_demographics` | Search quarterly demographics and market-structure data |
| `fdic_compare_bank_snapshots` | Compare two reporting snapshots across banks and rank growth and profitability changes |
| `fdic_peer_group_analysis` | Build a peer group and rank an institution against peers on financial metrics |
| `fdic_analyze_bank_health` | Run a CAMELS-style health assessment for a single institution |
| `fdic_show_bank_deep_dive` | Render a ChatGPT bank deep-dive dashboard for a single institution |
| `fdic_ubpr_analysis` | Run a UBPR-equivalent ratio analysis (ROA, ROE, NIM, efficiency, capital, liquidity, growth) |
| `fdic_compare_peer_health` | Rank a group of institutions by CAMELS-style health scores |
| `fdic_detect_risk_signals` | Scan institutions for early warning risk indicators |
| `fdic_analyze_credit_concentration` | Analyze loan portfolio composition and CRE/construction concentration relative to capital |
| `fdic_analyze_funding_profile` | Analyze deposit composition, wholesale funding reliance, and funding risk signals |
| `fdic_analyze_securities_portfolio` | Analyze securities portfolio size, MBS concentration, and interest rate exposure |
| `fdic_franchise_footprint` | Map branch and deposit distribution across MSA markets using SOD data |
| `fdic_market_share_analysis` | Rank institutions by deposit market share in an MSA or city market and compute HHI |
| `fdic_holding_company_profile` | Profile a holding company and its FDIC-insured subsidiaries with aggregated metrics |
| `fdic_regional_context` | Provide regional economic context (unemployment, interest rate environment) for a bank's market |

Server-side analysis helpers:

- `fdic_compare_bank_snapshots` batches roster lookup, financial snapshots, and optional demographics snapshots inside the MCP server
- `fdic_peer_group_analysis` builds a peer group from asset size, charter class, and geography criteria and then ranks an institution against peers
- `fdic_analyze_bank_health` returns a full `public_camels_proxy_v1` proxy assessment; `fdic_compare_peer_health` returns per-institution summary scores with a full proxy for the subject; `fdic_detect_risk_signals` uses the proxy engine to generate per-institution risk signals — all are analytical proxies, not official regulatory CAMELS ratings

## Claude Code Skills

This repository includes a [Claude Code](https://claude.ai/claude-code) slash command that chains multiple FDIC MCP tools into a structured analysis workflow.

| Skill | Command | Description |
|-------|---------|-------------|
| Bank Deep Dive | `/fdic-bank-deep-dive` | Comprehensive single-institution analysis report covering health assessment, financial performance, peer benchmarking, credit concentration, funding profile, securities portfolio, franchise footprint, and economic context. Accepts a bank name or CERT number with an optional report date. |

Skills are defined in `.claude/commands/` and are available to any Claude Code session with this MCP server configured. See [docs/usage-examples.md](./docs/usage-examples.md) for a usage example.

## Data Notes

- Monetary values are generally reported in thousands of dollars.
- `CERT` is the stable FDIC institution identifier.
- Financial and demographics datasets are quarterly and use `REPDTE` in `YYYYMMDD`.
- Summary data is annual and uses `YEAR`.
- SOD data is annual branch-level data as of June 30.
- Do not mix quarterly financial data and annual branch data without stating the date basis.

## Support

Use the GitHub issue tracker for bugs, documentation problems, and feature requests: <https://github.com/jflamb/fdic-mcp-server/issues>

The main support docs are:

- [docs/support.md](./docs/support.md)
- [docs/prompting-guide.md](./docs/prompting-guide.md)
- [docs/usage-examples.md](./docs/usage-examples.md)
- [docs/troubleshooting.md](./docs/troubleshooting.md)
- [SECURITY.md](./SECURITY.md)

## Contributing

Contributor guidance lives in [CONTRIBUTING.md](./CONTRIBUTING.md).

For local validation, run:

```bash
npm run typecheck
npm test
npm run build
```

Releases are published automatically from validated `main` commits by `semantic-release`. Do not manually edit the package version or create release tags by hand. GitHub Releases is the authoritative release record for published versions.

## License

This project is licensed under the MIT License.