faa-aircraft-registry-mcp-server

<div align="center">
  <h1>@cyanheads/faa-aircraft-registry-mcp-server</h1>
  <p><b>Decode N-numbers to aircraft, engine, status, and owner; search the US civil aircraft registry by owner, type, or state; resolve active/deregistered/reserved status — offline via MCP. STDIO or Streamable HTTP.</b>
  <div>5 Tools • 1 Resource</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.1.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/faa-aircraft-registry-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/%40cyanheads%2Ffaa-aircraft-registry-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/faa-aircraft-registry-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/faa-aircraft-registry-mcp-server/releases/latest/download/faa-aircraft-registry-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=faa-aircraft-registry-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZmFhLWFpcmNyYWZ0LXJlZ2lzdHJ5LW1jcC1zZXJ2ZXIiXX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22faa-aircraft-registry-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Ffaa-aircraft-registry-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://faa-aircraft-registry.caseyjhand.com/mcp](https://faa-aircraft-registry.caseyjhand.com/mcp)

</div>

---

## Overview

The entire US civil aircraft registry as an offline lookup server. Resolve a tail number to its aircraft, make/model, engine, year, and registered owner; search by owner, type, or state; decode manufacturer and engine codes to specs; and resolve registration status across active, deregistered, and reserved records.

The data is the FAA's [Releasable Aircraft Database](https://registry.faa.gov/database/ReleasableAircraft.zip) — the full registry published by the FAA Civil Aviation Registry as a public-domain bulk download (a US Government work, no copyright). There is no keyless live FAA registry API, so the server builds a local index from that download instead: `MASTER` → `ACFTREF` → `ENGINE` are pre-joined into an embedded SQLite + FTS5 index, and every coded field is decoded at query time. Queries hit that local index — keyless, no runtime network, no per-request rate limit.

The index is **not bundled** with the package. On first use the operator runs `mirror:init` to download and build it (see [First-run setup](#first-run-setup)). Owner name and address are **redacted by default** (see [Owner-PII redaction](#owner-pii-redaction)).

Composes with live flight-tracking data: the Mode S (hex) code this server returns is the ICAO 24-bit address that OpenSky and similar feeds key on, so a tail number or transponder code seen in the air decodes here to its aircraft and status.

## Tools

Five tools covering the registry — two exact-key lookups, two full-text searches, and one cross-file status resolver. Searches return decoded summaries with N-numbers (or 7-char reference codes) to drill into via the matching lookup.

| Tool | Description |
|:---|:---|
| `faa_lookup_registration` | Decode one N-number to its full pre-joined active record — aircraft make/model, engine, year, airworthiness, registration status, Mode S code, and registered owner (when redaction is off). |
| `faa_get_registration_status` | Resolve an N-number across all three status files (active, deregistered, reserved) in priority order, returning a definitive `recordType`. |
| `faa_search_registrations` | Search active registrations by owner name, make/model, state, aircraft type, or Mode S code. |
| `faa_search_aircraft_types` | Search the aircraft reference table by manufacturer/model name, type, or category to discover manufacturer-model codes. |
| `faa_get_aircraft_type` | Decode a 7-char manufacturer/model/series code to aircraft specs — category, type, engine, seats, weight class, cruise speed, type-certificate data. |

### `faa_lookup_registration`

The primary tool. Decode one N-number to its full record in a single call.

- Accepts `N12345` or `12345` — the leading `N` is optional, and the number is normalized before lookup
- Resolves the `MASTER` → `ACFTREF` → `ENGINE` join and decodes every coded field (aircraft type, engine type, status, airworthiness class, region) — each surfaced as both the raw FAA code and the decoded label
- Returns the Mode S code in both octal and hex; the hex form is the ICAO 24-bit address used by live flight-tracking feeds
- Owner name/address are included only when `FAA_REDACT_OWNER_PII=false`; otherwise `ownerRedacted: true` flags that they were withheld
- A known-but-inactive number (deregistered or reserved) is *not found* here — use `faa_get_registration_status` for the cross-file answer

---

### `faa_get_registration_status`

Resolve where an N-number stands across the registry, even when it is no longer active.

- Checks the active (`MASTER`), deregistered (`DEREG`), and reserved (`RESERVED`) files in priority order, returning a discriminated `recordType`: `active`, `deregistered`, `reserved`, or `unknown`
- A number that was never issued resolves to `recordType: "unknown"` — a valid, informative answer rather than an error
- Each branch carries the fields relevant to that state (active: status + airworthiness + dates; deregistered: cancel date + serial; reserved: reservation type + reserve/purge dates)
- Owner-PII–free — returns status facts only

---

### `faa_search_registrations`

Full-text search over active registrations, returning decoded summaries with N-numbers for follow-up.

- Filter by `ownerName`, `makeModel`, `state`, `aircraftType`, or `modeSCode`; at least one filter is required
- **Owner-name search is disabled when `FAA_REDACT_OWNER_PII` is on** — search by make/model, state, type, or Mode S code instead
- Each result carries an N-number to pass to `faa_lookup_registration` for full detail
- Discloses truncation when the result count hits `limit` (1–200, default 25), so a partial result set is never mistaken for complete

---

### `faa_search_aircraft_types`

Discover the 7-char manufacturer/model/series codes by name before decoding them.

- Filter by `query` (manufacturer/model name, full-text), `aircraftType` code, or `category` code; at least one filter is required
- Returns reference summaries with the code to pass to `faa_get_aircraft_type`
- Discloses truncation at the `limit` (1–200, default 25)

## Resources

| Type | Name | Description |
|:---|:---|:---|
| Resource | `faa://registration/{nNumber}` | Full registration record for one N-number — the same decoded, pre-joined payload as `faa_lookup_registration`. |

All registry data is also reachable via tools — the resource is a convenience for clients that inject resources as context. Tool-only clients (the majority) reach the same record through `faa_lookup_registration`, so no data is locked behind the resource. Search collections are not exposed as resources; use the search tools instead.

## Features

Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):

- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
- Unified error handling — handlers throw, framework catches, classifies, and formats, with typed per-tool error contracts and recovery hints
- Pluggable auth: `none`, `jwt`, `oauth`
- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
- Structured logging with optional OpenTelemetry tracing
- STDIO and Streamable HTTP transports

FAA-registry-specific:

- Offline and keyless at runtime — every query hits the local SQLite + FTS5 index; no API key, no runtime network, no rate limit
- Built on the framework `MirrorService`: `mirror:init` builds the index out-of-band, and the HTTP server schedules a daily refresh aligned to the FAA's nightly re-release
- Pre-joined `MASTER` → `ACFTREF` → `ENGINE` records, so one call returns "2008 Cessna 172S, Lycoming IO-360, valid registration" rather than raw join codes
- Fail-safe owner-PII redaction — redaction defaults on and drops owner name/address from output *and* disables owner-name search

Agent-friendly output:

- Coded fields surface both the raw FAA code and the decoded label — the label for reasoning, the code so nothing is lost
- Truncation disclosure — search tools flag `truncated` with `shown`/`cap` when the result set is capped, so a partial page is never read as the whole
- Permissible-field honesty — fields the FAA leaves blank (year, cruise speed, co-owner names) stay absent rather than fabricated
- `ownerRedacted` flag on every affected payload, so the agent knows owner data was withheld and why
- Discriminated status output (`recordType`) so callers branch on data, not st