io.github.cyanheads/faa-aircraft-registry-mcp-server

@cyanheads/faa-aircraft-registry-mcp-server

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.

5 Tools • 1 Resource

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

Overview

The US civil aircraft registry, searchable offline from the FAA's Releasable Aircraft Database. Decode an N-number to its aircraft, engine, and registered owner; check whether it's active, deregistered, or reserved; and search by owner, make and model, state, or Mode S code.

Tools

Resources

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

Capability reference

faa_lookup_registration tool

• Accepts N12345 or 12345; the leading N is optional
• Returns decoded aircraft, engine, and status fields as raw code plus label, and the Mode S code in octal and hex (hex is the ICAO 24-bit address)
• Owner name and address appear only when FAA_REDACT_OWNER_PII=false; otherwise ownerRedacted: true
• Errors: not_found (no active registration; try faa_get_registration_status), invalid_n_number

faa_get_registration_status tool

• Checks the active, deregistered, and reserved files in that order
• recordType is active, deregistered, reserved, or unknown; a never-issued number returns unknown, not an error
• Status facts only, no owner data
• Error: invalid_n_number

faa_search_registrations tool

• Filters: ownerName, makeModel, manufacturerModelCode, state, aircraftType, modeSCode; at least one required, combined with AND
• limit 1–200 (default 25) with offset paging; responses report totalCount and nextOffset when truncated
• Each result carries an N-number to pass to faa_lookup_registration
• Errors: no_filters, invalid_code, invalid_state, invalid_mode_s_code, invalid_aircraft_type, and owner_search_disabled (owner-name search is off while FAA_REDACT_OWNER_PII is on)

faa_search_aircraft_types tool

• Filters: query (manufacturer/model name), aircraftType (1–9/H/O), category (1–3); at least one required
• Returns summaries with the code to pass to faa_get_aircraft_type or faa_search_registrations.manufacturerModelCode
• limit 1–200 (default 25) with offset paging; responses report totalCount and nextOffset when truncated
• Errors: no_filters, invalid_aircraft_type, invalid_category

faa_get_aircraft_type tool

• Accepts a 6–7-character uppercase alphanumeric manufacturer/model/series code; find codes with faa_search_aircraft_types
• Returns manufacturer, model, type, engine, category, seats, engines, weight class, cruise speed, and type-certificate data
• weightClass keeps the raw FAA string; weightClassLabel decodes it when known
• Errors: not_found, invalid_code

faa://registration/{nNumber} resource

• Same payload as faa_lookup_registration; application/json, cached 1 hour
• nNumber accepts N12345 or 12345
• Errors: not_found, invalid_n_number

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: queries hit a local SQLite + FTS5 index with no API key or rate limit
• Daily index refresh under HTTP transport, aligned to the FAA's nightly re-release
• Pre-joined records: one call returns decoded aircraft, engine, and status
• Owner name and address are redacted by default, and owner-name search is disabled until FAA_REDACT_OWNER_PII=false
• Mode S hex codes match the ICAO 24-bit addresses used by flight-tracking feeds

Agent-friendly output:

• Coded fields carry both the raw FAA code and the decoded label
• Capped search results flag truncated with shown and cap
• Fields the FAA leaves blank stay absent rather than filled in
• recordType and ownerRedacted let callers branch on data

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.

The Desktop MCPB includes Node's SQLite driver and its cross-platform prebuilts. Build the local index with the bundle's mirror CLI before querying.

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.

Build the index out-of-band (never on server startup — a full parse of ~1M rows must not block start). From a source checkout, run bun install && bun run build first. Then, from the checkout, installed package directory, or extracted MCPB directory, run the compiled commands below. Node and Bun both work; replace node with bun to use Bun's built-in SQLite. The Docker image supports bun run mirror:init, mirror:verify, and mirror:refresh.

# Build the local index from the live FAA download (idempotent, resumable)
FAA_MIRROR_PATH=/path/to/faa-registry.db node dist/cli/faa-mirror-init.js

# Verify it built (readiness + integrity check)
FAA_MIRROR_PATH=/path/to/faa-registry.db node dist/cli/faa-mirror-verify.js

# Rebuild from the latest FAA release (run on a schedule, or out-of-band for stdio)
FAA_MIRROR_PATH=/path/to/faa-registry.db node dist/cli/faa-mirror-refresh.js

• Keep the path stable. Point FAA_MIRROR_PATH (and the same env var in your MCP client config) at a persistent location so the built index is reused across runs. Default: .mirror/faa-registry.db.
• Daily refresh. Under HTTP transport the server schedules a daily mirror:refresh aligned to the FAA's nightly re-release (~11:30 PM Central). If an interrupted rebuild leaves the index empty, queries fail loudly with ServiceUnavailable until the rebuild succeeds. Under stdio, run mirror:refresh out-of-band (e.g. a cron job).
• Docker. The image ships the mirror CLI and a writable .mirror data directory owned by the runtime user. Mount a volume there and run mirror:init once (e.g. docker exec <container> bun run mirror:init, or a one-shot init job against the shared volume) so the index persists across container restarts.
• Until the index exists, every query fails with a ServiceUnavailable error whose recovery hint points to mirror:init — there is no live API to fall back to, so the cold state surfaces loudly rather than returning empty results.

The source URL is overridable via FAA_DATABASE_URL (for a private or cached mirror); it is read only at ingest time, never per request.

Prerequisites

• Bun v1.4 or higher (or Node.js v24+). Bun uses built-in bun:sqlite; Node uses the included better-sqlite3 dependency, with bundled N-API prebuilts for macOS, Windows, and Linux (glibc/musl), on x64 and arm64.
• Disk space for the built index (a few hundred MB) at FAA_MIRROR_PATH.
• Network access at mirror:init / mirror:refresh time to download the FAA ZIP. Not needed at query time.

Installation

For local development or self-hosting from source:

1. Clone the repository:

git clone https://github.com/cyanheads/faa-aircraft-registry-mcp-server.git

1. Navigate into the directory:

cd faa-aircraft-registry-mcp-server

1. Install dependencies:

bun install

1. Compile the server and build the index (see First-run setup):

bun run build
bun run mirror:init

Configuration

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Build the local index (see First-run setup)
  bun run mirror:init
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest unit and integration tests
  bun run test:package # npm tarball + cleaned MCPB runtime checks
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t faa-aircraft-registry-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 \
  -v faa-registry:/usr/src/app/.mirror faa-aircraft-registry-mcp-server
# Build the index once against the mounted volume:
docker run --rm -v faa-registry:/usr/src/app/.mirror faa-aircraft-registry-mcp-server bun run mirror:init

The Dockerfile defaults to HTTP transport with stateless sessions, ships the mirror:init/mirror:refresh/mirror:verify CLI, pre-creates a writable .mirror data directory owned by the runtime user (mount a volume there and run mirror:init once to build and persist the index), and logs to /var/log/faa-aircraft-registry-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

The FAA Releasable Aircraft Database is a public-domain US Government work, published by the FAA Civil Aviation Registry. This project redistributes none of that data; operators download it directly from the FAA at install time.