Ourairports Mcp Server

Overview

Offline aviation reference data from the public-domain OurAirports dataset — airports, runways, navaids, and radio frequencies, bundled with the package rather than fetched at runtime. Resolve an airport by any code, search by name or facets, ground a coordinate in the nearest airports or navaids, and look up the countries and regions in the dataset. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

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.

Capability reference

ourairports_search_airports _tool

• 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
• limit accepts 1–100 rows and defaults to OURAIRPORTS_DEFAULT_SEARCH_LIMIT (20); truncation reports the total matched count, cap, and recovery guidance

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
• 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
• 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
• limit accepts 1–100 rows and defaults to OURAIRPORTS_DEFAULT_SEARCH_LIMIT (20); truncation reports the total matched count, cap, and recovery guidance

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 plus per-end displaced thresholds (leDisplacedThresholdFt / heDisplacedThresholdFt)
• 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–500, default 100); limit (1–50) defaults to OURAIRPORTS_DEFAULT_SEARCH_LIMIT, clamped to this tool's 50-row max; 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 limit; truncation reports the cap and recovery guidance (narrow radius_km, add type, or raise limit)
• Empty-radius guidance suggesting a wider radius_km

ourairports_find_navaids _tool

• Coordinate mode: latitude + longitude (+ optional radius_km, 1–500, default 100) ranks navaids nearest-first with distance and bearing; limit (1–50) defaults to OURAIRPORTS_DEFAULT_SEARCH_LIMIT, clamped to 50
• Airport mode: airport_code returns the navaids serving that airport
• Exactly one mode required — supplying both or neither is a mode_conflict validation error
• 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 limit in both modes; truncation reports the cap and recovery guidance
• 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 continent filter (AF, AN, AS, EU, NA, OC, SA); optional include_regions nests each country's ISO 3166-2 regions with their airport counts
• Airport counts exclude closed airports
• Countries sorted by name; the lookup table for valid country / region filter values used by ourairports_search_airports
• Empty continent match returns a notice suggesting a call without the filter

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, an ident-keyed navaid join, 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

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

Public Hosted Instance

A public instance is available at https://ourairports.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP, with this client config:

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

Self-Hosted / Local

Add the following to your MCP client configuration file.

{  "mcpServers": {    "ourairports-mcp-server": {      "type": "stdio",      "command": "bunx",      "args": ["@cyanheads/ourairports-mcp-server@latest"],      "env": {        "MCP_TRANSPORT_TYPE": "stdio",        "MCP_LOG_LEVEL": "info"      }    }  }}

Or with npx (no Bun required):

{  "mcpServers": {    "ourairports-mcp-server": {      "type": "stdio",      "command": "npx",      "args": ["-y", "@cyanheads/ourairports-mcp-server@latest"],      "env": {        "MCP_TRANSPORT_TYPE": "stdio",        "MCP_LOG_LEVEL": "info"      }    }  }}

Or with Docker:

{  "mcpServers": {    "ourairports-mcp-server": {      "type": "stdio",      "command": "docker",      "args": [        "run", "-i", "--rm",        "-e", "MCP_TRANSPORT_TYPE=stdio",        "ghcr.io/cyanheads/ourairports-mcp-server:latest"      ]    }  }}

No API key is required — the dataset ships with the package and the image.

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

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• No API key, account, or external service — all data is bundled.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/ourairports-mcp-server.git

2. Navigate into the directory:

cd ourairports-mcp-server

3. Install dependencies:

bun install

4. Fetch and bundle the dataset (writes the six CSVs into data/):

bun run build:data

Refreshing the data

The bundled snapshot is as fresh as the last build:data run (or, for the Docker image, the last build). To pull the latest daily drop from the OurAirports mirror, re-run bun run build:data and rebuild. To point at an existing local data drop without rebuilding, set OURAIRPORTS_DATA_DIR.

Configuration

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

Running the server

Local development

• Build and run:

  sh

  # One-time data fetch + buildbun run build:databun run rebuild
  # Run the built serverbun run start:stdio# orbun run start:http

• Run checks and tests:

  sh

  bun run devcheck   # Lint, format, typecheck, securitybun run test       # Vitest test suitebun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t ourairports-mcp-server .docker run --rm -i -e MCP_TRANSPORT_TYPE=stdio ourairports-mcp-server

The build stage runs bun run build:data so the dataset is fetched and baked into the image — the resulting container is fully self-contained and makes no network calls at runtime. The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/ourairports-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
• 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:

bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.