Overview

ourairports-mcp-server is the static aviation reference layer for resolving airport identifiers and grounding coordinates. It answers what exists — the catalog of airports, their codes, runways, navaids, and radio frequencies — to complement live aviation services that answer what is happening (weather, positions).

The entire OurAirports dataset is dedicated to the public domain and published as flat CSVs. Those six CSV files — airports, runways, navaids, airport frequencies, countries, and regions (~178k rows, ~20 MB) — are bundled into the package and baked into the Docker image at build time. At startup the server parses them into in-memory indices; every tool is then a local query. The result has no API key, no rate limit, and no upstream dependency to inherit an outage from.

How the working model fits together:

• Code resolution across five identifier spaces. Airports carry IATA, ICAO, GPS, local, and the OurAirports ident. A single code parameter resolves against a unified index (priority: ident → ICAO → IATA → GPS → local), and the response echoes the full code set so an ambiguous national code is self-correcting. A missing code (no IATA for a small field) is reported as null, never a 404.
• Nearest-neighbour by great-circle distance. Coordinate lookups run a haversine scan over a flat Float64Array of every airport (or navaid) position and return the nearest results ranked by distance, each with its bearing — sub-millisecond at this scale, no spatial index needed.
• Honest sparsity. Absent upstream fields (no elevation, null runway dimensions) surface as unknown. Capped result lists disclose truncation.

OurAirports is community-edited. The data is surfaced as-is and is not authoritative for real flight operations — treat it the way you would any crowd-sourced reference.

Tools

Six read-only tools, all local queries against the bundled index — code resolution and detail, airport and runway search, coordinate grounding, navaids, and the country/region lookup table:

ourairports_search_airports

The common entry point — search by free text, facets, or both.

• Free-text search over name, municipality, and keywords; tokens are AND-matched (word order and partial words handled)
• Faceted filters: country (ISO 3166-1 alpha-2), region (ISO 3166-2), and type — country/region are exact match, case-insensitive, with surrounding whitespace ignored
• Closed airports excluded by default; opt in with include_closed
• Results ranked operational/larger-airports-first, each with its full code set and coordinates for chaining into ourairports_get_airport
• Truncation disclosure — total matched count, applied cap, and guidance to broaden or narrow

ourairports_search_runways

Cross-airport runway search — the counterpart to ourairports_get_airport, which lists runways for one already-known airport.

• Airport facets (country, region, type) narrow the airports first; runway facets (surface, min_length_ft, min_width_ft, lighted) then filter their runways
• surface is a case-insensitive substring match against the raw upstream surface string (no controlled vocabulary — a shorter fragment like asp matches ASP, ASPH, and Asphalt), not an exact code
• Returns one flat { airport, runway } row per matching runway — an airport with three matching runways contributes three rows
• A runway whose length or width is unknown is excluded when the matching min_*_ft filter is set — never assumed to meet a threshold the data can't confirm
• Closed airports and closed runways are both excluded unless include_closed_airports / include_closed_runways is set
• Truncation disclosure — total matched count, applied cap, and guidance to broaden or narrow

ourairports_get_airport

The detail tool — one call returns everything the common case needs.

• Resolves a single code case-insensitively across all five identifier spaces (priority: ident → ICAO → IATA → GPS → local); surrounding whitespace is ignored
• Runways and radio frequencies inline; include trims the response to a subset, and the output's included field distinguishes a relation omitted by include from one that genuinely has no records
• Echoes the airport's complete code set plus a resolvedVia / resolutionNote, with an ambiguity warning for shared national codes so a wrong resolution is self-correcting
• Absent codes reported as null; closed airports always resolve
• unknown_code error with a recovery hint when no identifier space matches

ourairports_find_airports

The grounding tool — turn a latitude/longitude into the nearest airport(s).

• Great-circle (haversine) ranking, nearest-first, each result with distanceKm and bearingDeg (degrees true) from the query point
• radius_km (1–500, default 100), optional type filter, include_closed opt-in
• Coordinate in, ranked airports out — no geocoding; resolve place names to lat/lon upstream first
• Empty-radius guidance suggesting a wider radius_km

ourairports_find_navaids

Navigation aids two ways — spatially or by airport.

• Coordinate mode: latitude + longitude (+ optional radius_km) ranks navaids nearest-first with distance and bearing
• Airport mode: airport_code returns the navaids serving that airport
• Exactly one mode required — supplying both or neither is a validation error
• Frequencies surfaced in both kHz (the stored value — a VOR on 114.5 MHz reads frequencyKhz 114500) and MHz
• Airport mode distinguishes "airport not found" (unknown_code error) from "airport found but has no associated navaids" (empty list with a note)

Resource and prompt

The airport://{code} resource is a stable-URI twin of ourairports_get_airport for clients that inject resource context. All data is reachable from the tools alone — tool-only clients lose nothing. The corpus is not exposed as a resource list (enumerating 85k airports is a dump, not a discovery aid); discovery is ourairports_search_airports.

Features