@cyanheads/aviation-weather-mcp-server

Public Hosted Server: https://aviation-weather.caseyjhand.com/mcp

Overview

Aviation weather from the NWS Aviation Weather Center — METARs, TAFs, PIREPs, and domestic SIGMETs. Look up stations, fetch current and forecast conditions, and pull pilot reports and hazard advisories from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Prompts

Related MCP server: mcp-metar

Capability reference

aviation_find_stations tool

• Look up one or more stations by identifier (up to 20 per call) — a lookup matches the registry's own ID, which for an airport is its 4-character ICAO ID (e.g., KSEA, K0S9); a 3-letter IATA code never resolves, though each record includes its IATA/FAA aliases when available

• Discover stations within a geographic bounding box, or list stations for one of the 50 US states or DC via two-letter USPS code

• Returns data_types (METAR, TAF, etc.) so agents can confirm what's available before querying

• Every result states whether the upstream 400-row cap cut it; limit (1–400) bounds how many stations a bbox or state search returns, ordered by ICAO identifier ascending with identifier-less stations last — rejected alongside station_ids, since that mode already names the set. An area search returning more than 130 stations with no limit says so and names the lever; omitting limit still returns every match

• An ID lookup names every identifier that resolved to nothing, separating a 3-letter IATA code (never resolves) from an identifier the registry simply does not list

• Whitespace around an ID is trimmed rather than failing the batch; only an empty or whitespace-only entry is rejected

aviation_get_metar tool

• station_ids (1–10 per call — 4 uppercase letters or digits, so K0S9-style identifiers work) for named airports, or bbox to survey every reporting station in an area — mutually exclusive

• hours (1–12) is a lookback window, not a row limit: with station_ids every observation inside it is returned, and with bbox the result is the latest observation per station

• flight_category (e.g., ["IFR", "LIFR"]) narrows a bbox survey to the stations in those categories — judged on each station's latest observation, applied before limit, and disclosed with the count surveyed before it; a station AWC could not rate never matches, and a survey the filter empties returns an empty result that says so. Rejected alongside station_ids

• A bbox survey states whether the upstream 400-row cap cut it and, above hours: 1, names hours as the first lever — a wide window spends the cap on repeat readings rather than on more stations; limit (1–400) bounds how many stations come back, ordered by station ID ascending, and is rejected alongside station_ids. A survey returning more than 40 stations with no limit says so and names the levers; omitting limit still returns every station

• Flight category (VFR/MVFR/IFR/LIFR) returned directly from the AWC API; decodes wind, visibility, present weather, and cloud layers alongside the raw METAR string

• Ceiling reports both height and kind (measured, or indefinite for vertical visibility into an obscuration) — sky_condition distinguishes a reported clear sky from an unreported one when clouds is empty

• metar_type distinguishes routine METAR from special SPECI observations

• Every batch reports which requested stations came back, naming missing IDs with recovery guidance

aviation_get_taf tool

• Accepts 1–4 ICAO station IDs per call

• Structured forecast periods with change types (FM, TEMPO, BECMG) and probabilities; weather decoded group by group beside the raw groups

• Forecast obscurations keep their layer and carry the vertical visibility into them, rather than reading as clear sky; sky_condition distinguishes an unamended period from a stated clear sky

• Text the upstream decoder left undecoded — often a fourth cloud layer — is surfaced per period in not_decoded rather than dropped

• Low-level wind shear (WS020/20040KT) decoded to the shear-layer top and forecast wind at that height

• valid_from / valid_to in ISO 8601 for time comparisons

• Every batch reports which requested stations came back, naming missing IDs with recovery guidance

aviation_get_pireps tool

• station_id + distance_nm (10–500 nm, 100 when omitted) for radial search, or bbox for area search — mutually exclusive; a station_id AWC does not recognize as a search center returns a typed error pointing to aviation_find_stations or bbox

• altitude_min_ft / altitude_max_ft filter to a cruise-altitude band in feet MSL, from 0 to 60000 ft (min must not exceed max); a report with unknown altitude is dropped once either bound is set

• min_intensity (lgt / mod / sev) restricts to reports carrying a turbulence or icing layer at that intensity or above — a matching report still carries its lighter layers

• Turbulence and icing arrays include up to two layers per report; icing layers the API synthesized for a report that never mentioned ice are dropped

• Outside air temperature (temp_c), wind aloft (wind), and the /WX flight weather decoded beside its raw groups (weather), for PIREPs and AIREPs alike. The wind direction is published as reported, with no conversion — a PIREP /WV direction is magnetic, unlike the true-north METAR and TAF winds

• Every result states whether the upstream 400-row cap cut it, naming only the narrowing levers the call can still use, and limit (1–400) bounds how many reports come back, ordered by recency. A result of more than 50 reports with no limit says so and names the lever; omitting limit still returns every match

• PIREPs are sparse by nature — absence of reports does not mean smooth conditions

aviation_get_advisories tool

• advisory_type: sigmet or all (default) — both return the active SIGMET set

• hazard filter (CONVECTIVE, TURBULENCE, ICING, IFR) applied upstream by AWC; bbox filtered client-side by polygon overlap

• AIRMETs are not served — the upstream feed carries domestic SIGMETs only, and a request for one (or its MTN OBSCN / SURFACE WIND / LLWS hazards) is rejected with guidance rather than answered with SIGMETs

• An empty result is a valid fair-weather state, and names what emptied it — nothing active, no advisory carrying the hazard, or none intersecting the bbox — so a filter that needs broadening isn't mistaken for quiet weather

aviation_preflight_brief prompt

• Arguments: departure_icao and destination_icao required; alternates (comma-separated ICAOs), departure_time (ISO 8601 UTC), cruise_altitude (feet MSL), and route_waypoints (semicolon-separated lat,lon pairs) optional

• Calls aviation_get_metar, aviation_get_taf, aviation_get_pireps, and aviation_get_advisories in sequence, chunked to each tool's station-per-call limit

• departure_time selects the TAF forecast period the briefing is read against; cruise_altitude bounds the PIREP search to a ±3,000 ft band; route_waypoints become the advisories bbox, widened by 1° on each side

• Omitting any of the three still generates the briefing, naming the assessment it could not make

• Reports weather risk rather than a go/no-go recommendation — that decision needs pilot, aircraft, and operational-minima context this server does not hold

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.

Aviation-weather-specific:

• Keyless — no API key or authentication required; all data is from the public AWC Data API

• Single service (aviation-weather-service) with retry + exponential backoff for the keyless public endpoint

• Raw coded strings (raw_metar, raw_taf, raw_pirep, raw_text) surfaced alongside decoded fields so agents have both layers

• State→bbox table enables US-state station queries that the AWC API doesn't natively support

• Server-level instructions field surfaces the "not an official briefing" safety disclaimer to all clients on initialize

Agent-friendly output:

• Discriminated output — flight category (VFR/MVFR/IFR/LIFR) as a typed string field, so agents branch on it without parsing ceiling and visibility

• Structured error contracts — typed reason fields with recovery hints (e.g., "Verify ICAO IDs with aviation_find_stations")

• Partial-result reconciliation — batch tools report requested / returned / missing / partial fields, so a short batch is never mistaken for full coverage

• Workflow sequencing — the aviation_preflight_brief prompt encodes the correct METAR → TAF → PIREPs → advisories sequence, chunks each step to the tool's station limit, and names the assessments it could not make

Getting started

Public Hosted Instance

A public hosted instance is available at https://aviation-weather.caseyjhand.com/mcp. Add it to your MCP client configuration:

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

Self-Hosted / Local

Add the following to your MCP client configuration file.

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

Or with npx (no Bun required):

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

Or with Docker:

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

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 required — the AWC Data API is fully public and keyless.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd aviation-weather-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env if you need to override AWC_BASE_URL or AWC_TIMEOUT_MS

Configuration

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

Running the server

Local development

• Build and run:

  bun run rebuild
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

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

Docker

docker build -t aviation-weather-mcp-server .
docker run --rm -p 3010:3010 aviation-weather-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/aviation-weather-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 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 prompts in the createApp() arrays in src/index.ts

• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Not an official preflight briefing. Data from the AWC is informational only. Real flight planning requires an authorized source (e.g., Leidos/1800wxbrief.com). The server surfaces this disclaimer via its instructions field sent on every initialize.

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.