Ntsb Investigations README

@pipeworx/ntsb-investigations

NTSB aviation accident/incident investigations — plane crashes — searchable by aircraft registration (tail number), make/model, or by date range/state/ injury level across every make. Returns NTSB number, event date, location, injury level, phase/occurrence, probable cause, findings, and the NTSB docket link for each match.

Part of Pipeworx — an MCP gateway connecting AI agents to 1867+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.

Tools

• ntsb_search_investigations({ registration?, make?, model?, year?, state?, injury_level?, limit? }) — requires registration or make. model narrows within a make (matches "172", "172S", "172N", ... by prefix). year filters by event year, and is also how a registration match is narrowed when an N-number has been reassigned to a different aircraft over time (see below). injury_level (fatal, serious, minor, none) filters by the event's highest reported injury. Returns { found, data_as_of, source, count, query, results[] }, or { found: false, data_as_of, source, query } with no matches.
• ntsb_accidents_by_period({ from, to?, state?, injury_level?, limit? }) — aviation accidents/incidents in a date range, ACROSS every aircraft make (no make/registration needed). Answers "fatal aviation accidents in Alaska in 2025", "plane crashes by state in May 2024", etc. in one call. from/to accept "YYYY", "YYYY-MM", or "YYYY-MM-DD" and are both inclusive; to defaults to the end of from's own year/month when omitted. A range spanning more than 8 calendar years is refused — narrow it. Returns { found, data_as_of, source, count, truncated, query, by_state: [{ state, count }], results[] } — by_state covers every match regardless of the limit on results.

Auth

Keyless. No upstream account, no API key.

Data sources

• https://data.ntsb.gov/avdata — the NTSB's own eADMS aviation accident database (avall.zip, a Microsoft Access .mdb bulk file, confirmed live 2026-10-07 at ~96 MB zipped / ~561 MB unzipped). This is the full, current dataset — the SAME data CAROL's aviation search queries, published as the bulk file NTSB itself ships for exactly this use.
• https://data.ntsb.gov/Docket/?NTSBNumber=NNN — the NTSB docket page for a given ntsb_number, where the final report and supporting documents are published. Confirmed live (HTTP 200) for a real case pulled from this same dataset.

Why not CAROL's own search, or the newer developer API

CAROL (data.ntsb.gov/carol-main-public), NTSB's modern search UI, was probed first. Its JSON endpoints (api/Query/Main, api/Query/FileExport) are undocumented, and every QueryGroups/QueryRules request shape reverse-engineered from a public third-party CAROL proxy and from NTSB's own CAROL-Guide.pdf returned HTTP 500 ("An unknown exception occured." / "An error has occurred.") — the frontend ships no devtools-free schema and the server gives no hint why the shape it wants differs from what a real browser session sends (likely a server-side session/anti-forgery requirement CAROL's own JS sets up before the first query).

NTSB also runs a newer REST API at developer.ntsb.gov (Aviation / Safety Recommendations / Data Dictionary APIs, via an Azure API Management gateway). That portal requires signing up for a developer account and a subscription key before any call succeeds — an authentication wall, which per this repo's standing rule is never a free pass to build around without a separate key decision, unlike the plain public bulk file this pack actually reads.

Refreshing the data

node mcps/ntsb-investigations/scripts/refresh.mjs [--local-mdb <path>] [--dry-run] [--r2-mode auto|api|wrangler] [--shard-max-bytes <n>]

Downloads avall.zip, unzips it, runs mdb-export (mdbtools — brew install mdbtools / apt install mdbtools) on five tables (aircraft, events, narratives, Findings, Events_Sequence, eADMSPUB_DataDictionary), joins them into one flat case-per-aircraft list, then shards it into the shared pipeworx-datasets R2 bucket (same bucket as mcps/indiana-code, mcps/illinois-code, mcps/crs-reports — see scripts/lib/statute-store.mjs) rather than writing one object:

• ntsb/by-make/<slug>.json — one array per manufacturer. A make whose flat shard would exceed ~4 MB (only CESSNA, at this pull) is split further into ntsb/by-make/<slug>/<year>.json.
• Manufacturers with under 5 rows (most of the ~4,174 distinct raw acft_make strings — OCR/data-entry variants, not real distinct makers) are pooled into 16 ntsb/by-make/_other/<bucket>.json shards by a stable hash, rather than one tiny file each.
• ntsb/by-registration.json — normalised registration -> the (make, year) pairs it appears under, so a registration query knows which shard(s) to read without a full scan.
• ntsb/by-year/<YYYY>.json — one array per event year, ACROSS every make. The by-make shards above are keyed on make first, so a cross-make question ("fatal accidents in Alaska in 2025") would need every make's shard to answer from them; this orthogonal index answers it with one read per year in the requested range instead. Split further into ntsb/by-year/<YYYY>/<MM>.json only if a single year's shard ever exceeds the same ~4 MB threshold (not observed at this pull — years are well under 2 MB each).
• ntsb/manifest.json — data_as_of, source, record_count, and for every make the exact shard shape (flat / by_year + its years / bucket), plus a parallel years map for the by-year shards, so the read path never has to probe R2 to find out which key lives where.

This replaced an earlier single-object design (ntsb/aviation-cases.json, ~27 MB) that re-fetched and parsed the whole dataset on every call with no cache — two concurrent calls held two full parses in one isolate at once. src/index.ts now reads the manifest plus exactly the shard(s) one query needs (one, for a make/model query; the few a reused registration's distinct (make, year) pairs resolve to, for a registration query) and never reads the old monolith, which this script deletes from the bucket once the shards are up. No module-scope cache, on purpose — see the header comment in src/index.ts. No Supabase migration; storage is R2 only. --local-mdb re-uses an already-downloaded avall.mdb instead of re-pulling 96 MB. data_as_of in every response is the date the refresh last ran, not a per-record field from the upstream.

Registration (N-number) reuse

Tail numbers are reassigned by the FAA to different aircraft over time. ntsb_search_investigations({ registration }) does not silently collapse this: every historical match for that tail number comes back, each with its own event_date, make, and model. Pass year to narrow to one incarnation when more than one comes back for the same registration.

A broad make may ask you to narrow it

A handful of common manufacturers (CESSNA, at this pull) have enough rows that their data is split into one shard per year. A query for one of those makes with neither model nor year would have to read every one of that make's year-shards to answer — not a full dataset scan, but not the one or two small objects every other query costs either. Past a small fixed number of year-shards, the tool refuses with a message asking for year (or model, which does not change which shards get read but narrows the point of asking) instead of silently doing the larger read. A make/model/year combination, or an uncommon make on its own, is unaffected.

Date-range / cross-make queries

ntsb_search_investigations is keyed on make/registration, so there is no bounded way to answer "accidents in Alaska in 2025" or "fatal crashes in May 2024" from it without naming a make first. ntsb_accidents_by_period reads the orthogonal by-year index instead: one shard read per calendar year the from/to range touches (at most 8), then filters in memory by state and injury_level and groups the result by state. A range spanning more than 8 calendar years is refused — narrow it to answer in a bounded number of reads.

Quick Start

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

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

What this endpoint actually serves

tools/list at https://gateway.pipeworx.io/ntsb-investigations/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 1867+ data sources. The only difference is which pack's tools are listed directly; ask_pipeworx reaches all of them from either one.

No MCP client? Call it over HTTP

curl -X POST https://gateway.pipeworx.io/v1/tools/ntsb_search_investigations \
  -H 'Content-Type: application/json' \
  -d '{"make":"Cessna","model":"172","year":2024,"limit":10}'

No account needed for the first calls. Inspect any tool: GET https://gateway.pipeworx.io/v1/tools/ntsb_search_investigations. Find one: POST https://gateway.pipeworx.io/v1/tools/search_packs with {"query":"..."}.

Run it from npm

@pipeworx/mcp-ntsb-investigations is a local stdio bridge to the Pipeworx gateway: your MCP client starts it with npx, and it forwards every call to the same https://gateway.pipeworx.io/ntsb-investigations/mcp endpoint shown above. It needs network access; there is no offline mode.

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

Without a key it calls anonymously, capped at 50 calls a day. A free account raises that to 200 a day: get a key at https://pipeworx.io/signup and add "env": { "PIPEWORX_API_KEY": "<your key>" } to the server entry. The key is sent as a Bearer token, the same way a hosted connection sends it, so calls are metered and billed exactly as they are there.

It lists only this pack's tools by default. Set PIPEWORX_META_TOOLS=1 to also list ask_pipeworx and the other gateway-wide tools.

Behind an HTTPS proxy: Node's built-in fetch does not read HTTPS_PROXY by default. Newer Node releases honour it when NODE_USE_ENV_PROXY=1 is set; check your Node version's documentation.

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 Ntsb Investigations data" })

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

More

• Docs and guides
• pipeworx.io

License

MIT