@pipeworx/sba-loans

U.S. Small Business Administration 7(a) and 504 loan data — "did this business get an SBA loan, from whom, how much, and did it pay it off" — kept current from SBA's own quarterly FOIA CSV extracts.

Part of Pipeworx — an MCP gateway connecting AI agents to 1576+ live data sources.

Phase 1 (this pack, shipped): 7(a) + 504. PPP is a separate phase 2 — not built yet, ~5GB, tracked on fleet #1921 as remaining work.

Tools

• sba_loan_lookup(borrower_name, state?, program?, limit?) — a borrower's loan(s): amount, lender, approval date, status, charge-off detail.
• sba_largest_loans(program?, naics_code?, state?, lender_name?, limit?) — largest loans by any combination of filters.
• sba_lender_league_table(program?, state?, naics_code?, limit?) — lenders ranked by loan count and dollar volume.
• sba_charge_off_aggregate(group_by, program?, state?, naics_code?, limit?) — charge-off rate/amount grouped by naics | state | lender | program.

Auth

Keyless. The gateway supplies data-store credentials to this pack automatically (see the pack's entry in workers/gateway/src/index.ts), same pattern as zillow and usaspending. No caller-facing key.

PERSONAL-DATA RULE (mandatory, harris-county precedent)

Many 7(a)/504 (and, when built, PPP) borrowers are sole proprietors — individual humans, not companies. Street addresses (borrower AND lender-side: BorrStreet, BankStreet, CDC_Street, ThirdPartyLender_Street) are dropped at ingest — scripts/sba-loans-transform.py never reads those source columns into the row it emits, so they cannot reach a stored row or a response no matter what the source CSV contains. Kept: business/borrower name, city, state, ZIP, NAICS, lender identity, amounts, dates, status. This is the same rule applied to Harris County civil dockets (supabase/migrations/dockets_005_harris_drop_pii.sql): the standing public-data sourcing rule covers bulk public loan records, not bulk redistribution of individuals' home addresses.

Data sources

• https://data.sba.gov/dataset/7a-504-foia — dataset page. Portal trap: the CKAN root /dataset/7-a-504-foia (with the hyphen) 404s; the real slug has no hyphen between "7" and "a".
• Direct CSV downloads (quarterly asof_YYMMDD stamp in the filename): https://data.sba.gov/sites/default/files/uploaded_resources/FOIA_7a_FY2020_Present_asof_<stamp>.csv, ..._FY2010_FY2019_..., and FOIA_504_FY2010_Present_asof_<stamp>.csv. Two more decades exist (7(a) FY1991-1999, FY2000-2009; 504 FY1991-2009, ~520MB more) — not ingested in phase 1 to keep the first load disciplined; easy to add later via the same transform script if demand shows up.
• No developer API — this is a bulk-CSV-only source.

Ingest harness

• supabase/migrations/195_sba_loans.sql — unified sba_loans table (both programs; 504's CDC and 7(a)'s bank are normalized into lender_name/lender_city/lender_state, with 504's separate ThirdPartyLender kept in its own columns rather than forced into the same slot) + RPC functions the tools above call.
• scripts/sba-loans-transform.py — per-program CSV → unified-schema CSV, computing a deterministic loan_key (there is no natural unique loan id in the source — LocationID is a lender/office code reused across unrelated loans, confirmed live 2026-09-13, not a loan identifier). loan_key hashes the fields that identify a specific loan (program, location_id, borrower, approval date, amount, NAICS) and excludes the fields SBA revises over a loan's life (status, PIF/charge-off dates, charge-off amount) — so a quarterly re-ingest updates a loan's outcome in place via ON CONFLICT (loan_key) DO UPDATE, instead of duplicating the row.
• scripts/sba-loans-upsert.sh — download → transform → batched staging-table drain into sba_loans (same crash-safe, disk-safe shape as scripts/usaspending-upsert.sh: batches commit independently, a failed run drops its staging table rather than leaving it to grow Supabase disk forever).
• .github/workflows/sba-loans-refresh.yml — quarterly cron (workflow_dispatch for manual/backfill runs) on a GH-hosted runner, because this needs a pooler connection string held as a GitHub Actions secret for the psql \copy, not a Cloudflare Worker.

Gotchas

• 7(a) and 504 spell "paid in full" differently in the source: "P I F" (7(a), with spaces) vs "PIF" (504, no spaces). sba_charge_off_aggregate only depends on the CHGOFF code, which IS consistent across both programs (verified live 2026-09-13: 300/2,050/751/3,313 for CHGOFF/EXEMPT/CANCLD/"P I F" in a 7(a) sample; 177/1,036/926/3,790 for the 504 equivalents) — but don't assume other status strings line up between programs.
• 504 has no SBAGuaranteedApproval, InitialInterestRate, FixedorVariableInterestInd, RevolverStatus, or SoldSecMrktInd — those columns are NULL for every 504 row by design (7(a)-only fields), not a data-quality issue.
• Do not fold this pack into finra, sec-adv, or any other financial-data pack — it is a different agency, different licence-free public-domain data, and its own table.

Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "sba-loans": {
      "url": "https://gateway.pipeworx.io/sba-loans/mcp"
    }
  }
}

What this endpoint actually serves

tools/list at https://gateway.pipeworx.io/sba-loans/mcp returns the tools in the table above plus the shared Pipeworx meta-tools — ask_pipeworx, discover_tools, search_within, remember/recall and the rest of the gateway-wide set. So the tool count you see is larger than this table: a single-pack endpoint currently lists roughly 30 shared tools alongside the pack's own. The connection's initialize response states its exact scope, and is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a scoped connection answer a question this pack does not cover — via ask_pipeworx, which routes across the whole catalog — without you adding a second MCP server. There is currently no way to mount a pack endpoint without them; if the extra schemas cost you more context than the routing is worth, connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed directly, instead of just this one's:

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

Both URLs reach the same gateway and the same 1576+ data sources. The only difference is which pack's tools are listed directly; ask_pipeworx reaches all of them from either one.

Standalone (no gateway account)

This package also runs as a local stdio MCP server — no Pipeworx account, no gateway round-trip:

{
  "mcpServers": {
    "sba-loans": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-sba-loans"]
    }
  }
}

Or run it directly to confirm it starts:

npx -y @pipeworx/mcp-sba-loans

It speaks MCP over stdin/stdout and answers initialize/tools/list/tools/call for only this pack's tools — none of the shared meta-tools the gateway connection above adds. Same source, same tools, no ask_pipeworx routing.

Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English — this works on the pack endpoint above as well as on the full gateway:

ask_pipeworx({ question: "your question about Sba Loans data" })

The gateway picks the right tool and fills the arguments automatically.

More

• Docs and guides
• pipeworx.io

License

MIT