@cyanheads/ourairports-mcp-server
Resolve airport codes (IATA/ICAO/GPS/local), search airports, find the nearest by coordinate, and look up runways, navaids, and radio frequencies from the bundled public-domain OurAirports dataset via MCP. STDIO or Streamable HTTP.
6 Tools • 1 Airport Resource • 1 Skill
Overview
Airports, runways, navaids, and radio frequencies worldwide from the public-domain OurAirports dataset, bundled for offline use. Resolve an airport by any code, search by name or facets, and find the airports and navaids nearest a coordinate.
Tools
Resources
All data is also reachable via ourairports_get_airport — tool-only clients lose nothing. Not exposed as a resource list (enumerating 85k airports is a dump, not a discovery aid); discovery is ourairports_search_airports.
The OurAirports guide covers ambiguous codes and multi-tool airport, navaid, and runway queries. Plugin installs include it; MCP clients can read skill://ourairports-guide/SKILL.md.
Capability reference
The four search/find tools accept offset (default 0). When more rows remain, pass nextOffset as the next request's offset, keeping the query and data snapshot unchanged. totalCount counts all filtered matches; truncated, shown, and cap describe a page with more results after it. A past-end page is empty but retains its total.
Page ceilings are 100 rows for search and 50 for find. Explicit positive integer limits above the ceiling clamp with a notice, request log, and counter increment. Set OURAIRPORTS_CLAMP_LIMITS=false to restore strict rejection. Omitted limits use OURAIRPORTS_DEFAULT_SEARCH_LIMIT (20), bounded by the tool's ceiling.
ourairports_search_airports tool
- Free-text search over name, municipality, and keywords; tokens are AND-matched (word order and partial words handled)
- Exact codes match across IATA, ICAO, GPS, local code, and ident; a code-only query ranks its holders before incidental text matches. Hyphenated codes match whole. Name tokens also accept
intl, rgnl, muni, fld, and mem alongside their full spellings. Stopword-only or punctuation-only queries retain their no-searchable-terms result; use ourairports_get_airport for an explicit code
- Faceted filters:
country (two letters), region (two letters followed by one or two hyphen-separated segments of 1–3 letters/digits), and type. Codes are case-insensitive with surrounding whitespace ignored; literal "" is unset, whitespace-only is invalid. Malformed codes fail argument validation; codes absent from the bundled tables raise unknown_country / unknown_region with discovery guidance. Valid codes with no matching airports remain empty successes
- Closed airports excluded by default; opt in with
include_closed
- Results carry the full code set, coordinates, and recorded keywords for chaining into
ourairports_get_airport; operational/larger-airport ranking applies within the code-match tier
ourairports_search_runways tool
- Airport facets (
country, region, type) narrow the airports first; runway facets (surface, min_length_ft, min_width_ft, lighted) then filter their runways
- Country/region facets follow the same shape, empty-string, normalization, and bundled-membership rules as
ourairports_search_airports; valid empty selections remain successful
surface accepts a case-insensitive substring or a nonempty array of substrings matched with OR. Raw values have no controlled vocabulary: asp matches ASP, ASPH, and Asphalt; con and pem cover other recorded surfaces
- Optional
latitude + longitude ranks qualifying runways by the parent airport's coordinates, with radius_km from 1–20,016 (default 100). Both coordinates are required together; a radius alone is invalid
- Returns one flat
{ airport, runway, distanceKm, bearingDeg } row per matching runway — an airport with three matching runways contributes three rows. Distance and bearing are null without coordinates; rows then retain dataset traversal order
lengthFt and min_length_ft are the full runway surface as OurAirports records it, including displaced thresholds and overruns — not usable takeoff or landing distance; each runway also carries leDisplacedThresholdFt / heDisplacedThresholdFt (null when none is recorded)
- 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
- Each runway also carries its end-center coordinates and elevation above mean sea level, distinct from displaced thresholds
ourairports_get_airport tool
- 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; when other airports carry the same code, the note names each one (ident, country, code space) and says whether resolution priority or dataset row order picked this airport, so a wrong resolution is self-correcting — pass the other airport's ident
- Runways carry full-surface
lengthFt, per-end displaced thresholds, and each end center's latitude, longitude, and elevation in feet above mean sea level
- Airport detail includes recorded keywords,
wikipediaLink, and homeLink; valid web links are clickable in text output, and malformed recorded values remain visible as text
- Absent codes reported as
null; closed airports always resolve
unknown_code error with a recovery hint when no identifier space matches
ourairports_find_airports tool
- Great-circle (haversine) ranking, nearest-first, each result with
distanceKm and bearingDeg (degrees true) from the query point
radius_km (1–20,016, default 100); optional type filter; include_closed opt-in
- Coordinate in, ranked airports out — no geocoding; resolve place names to lat/lon upstream first
totalCount is the filtered in-radius count before paging; nextOffset reaches farther results
- Empty-radius guidance suggests a wider radius only below the global ceiling
ourairports_find_navaids tool
- Coordinate mode:
latitude + longitude (+ optional radius_km, 1–20,016, default 100) ranks navaids nearest-first with distance and bearing
- Airport mode:
airport_code returns the navaids serving that airport
- Ident mode:
ident matches an exact navaid code, case-insensitively after trimming, and returns all holders in dataset order, including navaids without an associated airport. type can narrow shared idents
- Exactly one complete mode required — overlapping modes, no mode, or incomplete coordinates raise
mode_conflict; incomplete-coordinate messages name the missing counterpart
frequencyKhz is the stored value for every type (a VOR on 114.5 MHz reads 114500); frequencyMhz carries the VHF frequency of a VOR or VOR-DME and the paired VHF frequency of a DME, TACAN, or VORTAC, and is null for NDB and NDB-DME, which tune in kHz; an upstream -1 placeholder reads as null
- Each navaid carries its service-volume metadata as recorded upstream:
usageType (HI, LO, BOTH, TERMINAL, RNAV), power, magneticVariationDeg (actual, positive east), slavedVariationDeg (the variation built into the radials), and dmeFrequencyKhz (the DME's paired VHF frequency) — null where the dataset has no value
totalCount is the match count before paging in every mode. Non-coordinate results have null distance and bearing; airportIdent is populated only in airport mode
- Airport mode distinguishes "airport not found" (
unknown_code error) from "airport found but has no associated navaids" (empty list with a note)
- Airport mode adds a
resolutionNote when airport_code is also a code of other airports, naming them by ident — the same note ourairports_get_airport returns
ourairports_list_countries tool
- Optional
country and continent (AF, AN, AS, EU, NA, OC, SA) filters combine as AND; optional include_regions nests regions by their recorded country association (so KS-U-A belongs to XK)
- Use
{ "country": "US", "include_regions": true } for one country's regions. Unscoped include_regions returns the entire region table; unscoped and continent-only requests remain accepted
country uses the search tools' shape, normalization, and membership rules; "" is unset, whitespace-only is invalid, and an absent code raises unknown_country
- Airport counts exclude closed airports
- Countries sorted by name; the lookup table for valid
country / region filters used by ourairports_search_airports and ourairports_search_runways
- A country/continent mismatch returns an empty success with a notice naming both filters;
totalCount counts returned countries
airport://{code} resource
- Same record as
ourairports_get_airport, including the same resolutionNote — runways and radio frequencies always inline, so there is no include / included
code resolves case-insensitively across all five identifier spaces (priority: ident → ICAO → IATA → GPS → local)
unknown_code error with a recovery hint when no identifier space matches
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.
OurAirports-specific:
- Bundled, public-domain dataset baked into the package and Docker image — zero runtime API, no key, no rate limit, no upstream outage
- In-memory indices built once at startup: id maps, a priority-ordered unified code index, airport-ref joins for runways and frequencies, navaid indices for associated airports and exact idents, a flat
Float64Array of coordinates, country/region maps, and a tokenized text-search index
- Brute-force haversine nearest-neighbour over the coordinate array — a few milliseconds across 85k airports, no spatial-index dependency
- CSVs parsed by header name, not column position, so an upstream column reorder can't silently misalign fields
- Ranked queries retain at most
offset + limit candidates; unranked queries skip to the requested window. Both count every match
Agent-friendly output:
- Honest sparsity — absent upstream fields (no IATA, no elevation, null runway dimensions) surface as
null, never fabricated
- Self-correcting resolution — every airport record echoes its full code set and a
resolvedVia / resolutionNote that names every other airport sharing the code, by ident
- Text output that matches the structured output — coordinates render at full precision, and upstream text is Markdown-escaped in
content only, so names like GRASS&GRAVEL display as recorded
- Truncation and empty-result disclosure — total counts, applied caps, and recovery guidance so callers can broaden, narrow, or re-query without parsing prose
Getting started
Connect to the hosted server from Claude Code:
To run locally:
For other clients, add this to the MCP configuration file:
The package and Docker image include the dataset. For Docker or a source build, see Running the server.
Configuration
See .env.example for the full list of optional overrides.
Running the server
Local development
Source builds require Bun v1.4.4 or newer. The installed package also runs on Node.js v24 or newer.
-
Clone and install:
-
Build and run:
-
Run checks and tests:
Docker
The image serves stateless HTTP at http://localhost:3010/mcp and logs to /var/log/ourairports-mcp-server. For a stdio client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/ourairports-mcp-server:latest"]. To build locally, run docker build -t ourairports-mcp-server .. Use --build-arg OTEL_ENABLED=false to omit OpenTelemetry peers.
Refreshing the data
Run bun run build:data and rebuild to pick up the latest daily CSV snapshot. The build validates country and region codes and airport references before writing the bundle. Use bun run build:data --check to validate an existing bundle, or set OURAIRPORTS_DATA_DIR to use a local data drop without rebuilding.
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
- Surface upstream data as-is: report absent fields as
null, never fabricate missing values
Attribution
Airport, runway, navaid, and frequency data from OurAirports, dedicated to the public domain. Attribution is a courtesy, not a requirement. Source CSVs are published daily at davidmegginson.github.io/ourairports-data.
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.
Contributing
Issues are welcome. Run checks and tests before submitting:
License
Apache-2.0 — see LICENSE for details.