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 分