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">

</div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://faa-aircraft-registry.caseyjhand.com/mcp

</div>

---

Overview

The US civil aircraft registry, mirrored offline from the FAA's Releasable Aircraft Database — there is no live FAA registry API. Decode an N-number to its aircraft, engine, and registered owner; resolve active, deregistered, or reserved status; search by owner, make/model, state, or Mode S code; and decode manufacturer/model codes to full aircraft specs. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

| 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 6–7-character manufacturer/model/series code to aircraft specs — category, type, engine, seats, weight class, cruise speed, type-certificate data. |

Resources

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

Also reachable via faa_lookup_registration; search collections aren't exposed as resources.

Capability reference

faa_lookup_registration _tool

• Accepts N12345 or 12345 — leading N optional, normalized before lookup
• Resolves MASTER → ACFTREF → ENGINE and decodes every coded field (aircraft type, engine type, status, airworthiness class, region) as both raw code and label
• Returns the Mode S code in octal and hex; hex is the ICAO 24-bit address used by flight-tracking feeds
• Owner name/address included only when FAA_REDACT_OWNER_PII=false; otherwise ownerRedacted: true flags that they were withheld
• Typed errors: not_found (well-formed but no active registration — use faa_get_registration_status), invalid_n_number (malformed input)

---

faa_get_registration_status _tool

• Checks active (MASTER), deregistered (DEREG), and reserved (RESERVED) files in priority order
• Discriminated recordType: active, deregistered, reserved, or unknown — a never-issued number resolves to unknown, not an error
• Branch-specific fields populate per state (active: status + airworthiness + dates; deregistered: cancel date + serial + mfr/model code; reserved: reservation type + reserve/expiration/purge dates)
• Owner-PII-free — status facts only
• Typed error: invalid_n_number for malformed input

---

faa_search_registrations _tool

• Filters: ownerName, makeModel, state, aircraftType, modeSCode — at least one required
• Owner-name search disabled when FAA_REDACT_OWNER_PII is on; typed owner_search_disabled error names the alternative filters
• limit 1–200 (default 25) and offset pagination; every response reports totalCount, and a truncated page carries nextOffset
• Each result carries an N-number to pass to faa_lookup_registration for full detail
• Typed error: no_filters when no filter is supplied

---

faa_search_aircraft_types _tool

• Filters: query (manufacturer/model name, full-text), aircraftType code, category code — at least one required
• Returns reference summaries with the code to pass to faa_get_aircraft_type
• limit 1–200 (default 25) and offset pagination; every response reports totalCount, and a truncated page carries nextOffset
• Typed error: no_filters when no filter is supplied

---

faa_get_aircraft_type _tool

• Accepts a 6–7-character uppercase alphanumeric manufacturer/model/series code
• Returns manufacturer, model, aircraft type, engine type, category, builder certification, seats, engines, weight class, cruise speed, and type-certificate data
• Discover codes by name first via faa_search_aircraft_types
• Typed errors: not_found (well-formed code, no reference record), invalid_code (malformed input)

---

faa://registration/{nNumber} _resource

• Same payload as faa_lookup_registration — application/json, cached 1 hour, private scope
• nNumber accepts N12345 or 12345 (leading N optional)
• Typed errors: not_found, invalid_n_number — same conditions as the tool

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

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 — one call returns decoded aircraft, engine, and status instead of raw join codes
• Fail-safe owner-PII redaction — defaults on, drops owner name/address from output, and disables owner-name search while active
• Composes with live flight-tracking feeds — the Mode S hex code returned here is the ICAO 24-bit address that OpenSky and similar feeds key on

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
• Discriminated output — recordType and ownerRedacted flags let callers branch on data, not string parsing

Getting started

Public Hosted Instance

A public instance is available at https://faa-aircraft-registry.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "faa-aircraft-registry-mcp-server": {
      "type": "streamable-http",
      "url": "https://faa-aircraft-registry.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

First run requires building the local index — see First-run setup below. The package does not ship the FAA data; until mirror:init has run once, queries fail with a clear "run mirror:init" error.

Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "faa-aircraft-registry-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/faa-aircraft-registry-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FAA_MIRROR_PATH": "/path/to/faa-registry.db"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "faa-aircraft-registry-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/faa-aircraft-registry-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FAA_MIRROR_PATH": "/path/to/faa-registry.db"
      }
    }
  }
}

Or with Docker (mount a volume at /usr/src/app/.mirror so the built index persists across containers — build it once with docker exec … bun run mirror:init):

{
  "mcpServers": {
    "faa-aircraft-registry-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-v", "faa-registry:/usr/src/app/.mirror",
        "ghcr.io/cyanheads/faa-aircraft-registry-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

FAA_MIRROR_PATH points the server at the index that mirror:init builds — set it to a persistent path so the index survives across runs. Owner PII is redacted by default; set FAA_REDACT_OWNER_PII=false only on a trusted local install to expose owner detail.

First-run setup

The FAA Releasable Aircraft Database is not bundled with the package — it is a public dataset (~70 MB compressed, refreshed daily by the FAA) that the operator downloads and indexes once before first use. Building the index produces a local SQLite file of a few hundred MB.

After installing, build the index out-of-band (never on server startup — a full parse of ~1M rows must not block start):

# Build the local index from the live FAA download (idempotent, resumable)
FAA_MIRROR_PATH=/path/to/faa-registry.db bun run mirror:init

# Verify it built (readiness + integrity check)
FAA_MIRROR_PATH=/path/to/faa-registry.db bun run mirror:verify

# Rebuild from the latest FAA r