Ourairports Mcp Server

io.github.cyanheads由 GitHub 帳號 cyanheads 發布v0.3.0更新於 Nov 11, 2026

Offline global aviation reference: airports, runways, navaids, frequencies from OurAirports.

已驗證Streamable HTTP可網頁執行位置與生活資料與分析

概覽

AI 產生的概覽

離線航空參考資料:依任意代碼解析機場、搜尋機場與跑道,並從內建的 OurAirports 資料集找出附近機場與導航台。

可以做什麼
  • 依 IATA、ICAO、GPS、本地或 ident 代碼解析單一機場,並一併回傳跑道與無線電頻率
  • 依代碼、名稱、關鍵字、國家、地區或類型搜尋機場,支援分頁與是否納入已關閉機場
  • 依道面、最小長度或寬度、燈光及機場條件搜尋跑道,可選擇依座標由近到遠排序
  • 在指定經緯度半徑內尋找機場或導航台,依距離由近到遠回傳距離與方位
  • 列出國家與地區及機場數量,用來取得有效的篩選代碼
適用情境
適合助理需要機場、跑道、導航台或頻率資訊但不想呼叫外部 API 的情況:航線研究、把座標對應到附近機場,或查詢某個識別碼。它面向唯讀參考查詢,不適用於實際飛航作業。
執行需求
可使用託管的 HTTP 端點,或透過 npx 在本機執行(需 Node.js v24 或更新版本;原始碼建置需 Bun)。資料已內建,無需 API 金鑰、帳號或網路連線。選用環境變數可調整傳輸方式、連接埠、端點路徑、驗證模式、日誌等級、預設結果上限與資料目錄。
安裝前請注意
六個工具皆為唯讀,不會寫入、傳送或刪除資料。資料由社群編輯,僅與最近一次建置同步,不能作為實際飛航作業的權威依據。跑道長度包含位移入口與超跑道區域,並非可用的起飛或降落距離。導航台頻率以 kHz 儲存,機場頻率則以 MHz 表示。將 MCP_AUTH_MODE 設為 jwt 或 oauth 會對外開放 HTTP 服務並需要憑證。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Ourairports Mcp Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式,或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南,先向你展示發布者、端點和登入方式,經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.cyanheads%2Fourairports-mcp-server/install.md,並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前,先告訴我它的發布者、端點和登入方式,等我確認。不要把 API 金鑰寫進命令或我會提交的檔案;問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

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

README

@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

ToolDescription
ourairports_search_airportsSearch exact airport codes, names, keywords, and facets. Ranked summaries with offset continuation; closed airports excluded by default.
ourairports_search_runwaysSearch runways by surface, dimensions, lighting, and airport facets, optionally nearest-first from a coordinate. One row per matching runway.
ourairports_get_airportFull record for one airport resolved by any code (IATA/ICAO/GPS/local/ident), with its runways and radio frequencies inline.
ourairports_find_airportsAirports within a radius of a coordinate, ranked nearest-first by great-circle distance, with distance and bearing.
ourairports_find_navaidsNavigation aids near a coordinate, serving an airport, or sharing an exact navaid ident.
ourairports_list_countriesCountries with airport counts and optional nested regions, filtered by country and/or continent. The lookup table for valid country/region filters on both search tools.

Resources

ResourceDescription
airport://{code}Single airport record by any code (IATA/ICAO/GPS/local/ident), with runways and frequencies inline.

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:

sh
claude mcp add --transport http ourairports-mcp-server https://ourairports.caseyjhand.com/mcp

To run locally:

sh
claude mcp add ourairports-mcp-server -- npx -y @cyanheads/ourairports-mcp-server

For other clients, add this to the MCP configuration file:

json
{  "mcpServers": {    "ourairports-mcp-server": {      "command": "npx",      "args": ["-y", "@cyanheads/ourairports-mcp-server"]    }  }}

The package and Docker image include the dataset. For Docker or a source build, see Running the server.

Configuration

VariableDescriptionDefault
OURAIRPORTS_DATA_DIRDirectory holding the six OurAirports CSV files. Overridable to point at a fresher local data drop.Bundled data/
OURAIRPORTS_DEFAULT_SEARCH_LIMITDefault result cap for the search/find tools when the caller omits limit (1–100).20
OURAIRPORTS_CLAMP_LIMITSClamp explicit limits above each tool's page ceiling; false restores strict rejection.true
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for the HTTP server.3010
MCP_HTTP_ENDPOINT_PATHHTTP endpoint path where the server is mounted./mcp
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_SESSION_MODEHTTP session mode: stateful, stateless, or auto. This server uses stateless mode because no tool requests follow-up input.stateless
MCP_LOG_LEVELLog level (RFC 5424).info
LOGS_DIRDirectory for log files (Node.js only). Relative paths resolve from the server's package directory.<server-package>/logs
STORAGE_PROVIDER_TYPEStorage backend (unused on the data path — the index is in-memory).in-memory
OTEL_ENABLEDEnable OpenTelemetry instrumentation.false

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:

    sh
    git clone https://github.com/cyanheads/ourairports-mcp-server.gitcd ourairports-mcp-server && bun install
  • 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

sh
docker run --rm -p 127.0.0.1:3010:3010 ghcr.io/cyanheads/ourairports-mcp-server:latest

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

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools/resources and loads the bundled index at setup().
src/configServer-specific environment variable parsing and validation with Zod.
src/mcp-server/toolsTool definitions (*.tool.ts). Six read-only airport/runway/navaid tools.
src/mcp-server/resourcesResource definitions. The airport://{code} record.
src/services/airport-dataThe bundled-data service — CSV parsing, in-memory indices, code resolution, search, and the haversine geo scan.
scripts/build-data.tsBuild-time fetcher that bundles the six OurAirports CSVs into data/.
framework-skills/Project development skills synced from @cyanheads/mcp-ts-core.
tests/Unit and integration tests mirroring src/.

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:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

來源:README.md,提交 e3f1abd

工具

6

ourairports_search_airports

Search Airports

Search the bundled OurAirports corpus by exact airport code, free text (name, municipality, keywords), and/or facets (country, region, type). All query terms must match. Text supports forward prefixes and common abbreviations such as intl. Exact code matches lead code-only searches, followed by ranked summaries favoring operational and larger airports. Use ourairports_get_airport for full records by code, ourairports_list_countries for valid country and region codes, and ourairports_find_airports for nearest airports. OurAirports is community-edited — not authoritative for flight operations.

輸入參數typelimitqueryoffsetregioncountryinclude_closed

ourairports_search_runways

Search Runways

Search the bundled OurAirports corpus by airport and runway attributes. Returns one row per matching runway, paired with its airport. Supply latitude and longitude together to filter by radius and rank by distance to each parent airport. Surface matches any supplied fragment as a case-insensitive substring of the recorded surface. Lengths describe the full runway surface, including displaced thresholds and overruns. Minimum length and width filters exclude runways missing the corresponding measurement. Closed airports and runways are excluded unless their respective flags are set. Use nextOffset to continue the same query and ourairports_list_countries to find valid country and region codes. OurAirports is community-edited. Consult official sources for flight operations.

輸入參數typelimitoffsetregioncountrylightedsurfacelatitudelongituderadius_kmmin_width_ftmin_length_ft另有 2 個

ourairports_get_airport

Get Airport

Fetch the full record for one airport resolved by ANY code — IATA (SEA), ICAO (KSEA), GPS, national/local, or the OurAirports ident — with its runways and radio frequencies inline. The single `code` param is resolved case-insensitively across all five identifier spaces (priority: ident, then ICAO, IATA, GPS, local). The response always echoes the airport's complete code set and a resolutionNote naming which space matched; when other airports carry the same code, the note names each one (ident, country, code space) and why this airport won, so a wrong resolution is self-correcting — pass the other airport's ident to fetch it. Absent codes are reported as null, never an error. Runway lengths are the full runway surface (displaced thresholds and overruns included), not usable takeoff or landing distance. Closed airports always resolve. OurAirports is community-edited — not authoritative for flight operations.

輸入參數code必填include

ourairports_find_airports

Find Airports

Find airports within a radius of a latitude/longitude, ranked nearest-first by great-circle distance. Each result includes distance in kilometers and bearing in degrees true from the query point. Resolve place names to coordinates before calling. Use nextOffset to continue the same query. OurAirports is community-edited — not authoritative for flight operations.

輸入參數typelimitoffsetlatitude必填longitude必填radius_kminclude_closed

ourairports_find_navaids

Find Navaids

Find navigation aids (VOR, VOR-DME, DME, NDB, NDB-DME, TACAN, VORTAC) by exactly one mode: latitude+longitude with optional radius_km, airport_code for navaids serving an airport, or ident for every exact navaid-code holder. Coordinate results rank nearest-first with distance (km) and bearing (degrees true); airport and ident results retain dataset order. frequencyKhz is stored for every type; frequencyMhz is the VHF or paired-VHF frequency and is null for NDB and NDB-DME. Each navaid includes DME pairing, usage, power, and magnetic variation. totalCount counts filtered matches before paging; pass nextOffset as offset with the same query to continue. An unmatched ident or an airport with no associated navaids returns an empty list; an unknown airport_code is an error. Shared airport codes carry a resolutionNote naming the other airport idents. OurAirports is community-edited — not authoritative for flight operations.

輸入參數typeidentlimitoffsetlatitudelongituderadius_kmairport_code

ourairports_list_countries

List Countries

List countries and valid country/region filter codes for ourairports_search_airports and ourairports_search_runways, with airport counts excluding closed airports. Restrict to country for one country's regions; country and continent combine as AND. include_regions without a scope returns the entire region table, so prefer country for a one-country lookup. Unscoped and continent-only requests remain available.

輸入參數countrycontinentinclude_regions

版本歷史

6
  1. v0.3.0最新Nov 11, 2026
  2. v0.2.6Oct 19, 2026
  3. v0.2.5Oct 9, 2026
  4. v0.2.4Sep 24, 2026
  5. v0.2.3Sep 20, 2026
  6. v0.2.2Sep 16, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分