Aviation Weather Mcp Server

---

Tools

Five tools covering aviation weather — station lookup, current observations, terminal forecasts, pilot reports, and active advisories:

Tool	Description
aviation_find_stations	Resolve airports and weather stations by identifier, bounding box, or US state. Returns ICAO/IATA/FAA IDs, coordinates, elevation, and available data types.
aviation_get_metar	Get current weather observations (METARs) for one or more airports. Returns decoded wind, visibility, ceiling, present weather, temp/dewpoint, altimeter, cloud layers, flight category (VFR/MVFR/IFR/LIFR), and the raw METAR string.
aviation_get_taf	Get Terminal Aerodrome Forecasts for one or more airports. Returns each forecast period with valid times, surface wind, low-level wind shear, visibility, decoded weather, cloud layers, and vertical visibility into a forecast obscuration, plus the raw TAF string.
aviation_get_pireps	Get recent Pilot Reports near an airport or within a bounding box. Returns decoded turbulence, icing, and cloud reports with altitude, aircraft type, intensity, and the raw PIREP string.
aviation_get_advisories	Get active domestic SIGMETs for a region. Returns hazard type (CONVECTIVE, TURBULENCE, ICING, IFR), severity, altitude range, valid period, polygon coordinates, and raw text.

aviation_find_stations

Resolve and discover weather stations by multiple search modes.

• 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-letter ICAO ID and for a buoy or mesonet site is whatever that site carries. A 3-letter IATA code never resolves, though each returned record includes its IATA/FAA aliases when available
• Discover all stations within a geographic bounding box
• List stations for one of the 50 US states or DC via two-letter USPS code (uses bbox + client-side state filter)
• 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, so a truncated draw is never mistaken for every station in the area — a capped state query also reports the row count from before the state filter, and a smaller bbox is the named lever
• limit (1–400) bounds how many stations a bbox or state search returns without changing the area searched, ordered by ICAO identifier ascending with identifier-less stations (buoys, mesonet sites) last — so the same query and limit return the same stations, and a sampled state leads with airports rather than with sites carrying no ID. A limited result says so separately from the cap — a limit withheld stations that were examined, a cap dropped stations that were never drawn — and both can be reported at once without either implying the other. It belongs to the area modes; supplying it alongside station_ids is rejected, since that mode already names the set
• An ID lookup names every identifier that resolved to nothing instead of silently returning a shorter list, and separates the one shape it can diagnose — a 3-letter IATA code, which never resolves — from an identifier the registry simply does not list. Reconciliation matches the identifiers upstream returned, so a repeated or differently-cased ID is not reported as a gap
• Whitespace around an ID is trimmed rather than failing the batch — a padded entry resolves like the bare one, and only an empty or whitespace-only entry is rejected. No ICAO shape is imposed, so buoys and mesonet sites carrying no ICAO, IATA, or FAA identifier still resolve

---

aviation_get_metar

Fetch current or recent METAR observations (1–10 stations per call).

• hours (1–12) is a lookback window rather than a row limit — every observation inside it is returned, so a half-hourly station yields two rows at the default of 1
• Flight category (VFR/MVFR/IFR/LIFR) is returned directly from the AWC API — no client-side computation needed
• Decodes cloud layers, wind with gusts, visibility, and present weather (the raw groups plus plain English, one reading per group) in addition to the raw METAR string
• Ceiling covers broken, overcast, and obscuration layers, and reports whether the height was measured or is an indefinite ceiling — vertical visibility into an obscuration. An obscuration the station could not see up into (a VV/// group) reads as a ceiling of undetermined height rather than as no ceiling
• sky_condition carries the group an observation states when it publishes no layer heights (CLR, SKC, CAVOK, or OVX for a VV/// obscuration), so an empty clouds array with nothing beside it reads as a sky the station did not report rather than as a clear one
• METAR type field distinguishes METAR (routine) from SPECI (special observation triggered by significant weather change)
• Every batch reports which of the requested stations came back, so a partial result is never mistaken for full coverage — missing IDs are named with recovery guidance

---

aviation_get_taf

Fetch Terminal Aerodrome Forecasts for 1–4 airports.

• Returns structured forecast periods with change types (FM, TEMPO, BECMG) and probabilities
• Forecast weather decoded group by group beside the raw groups (-SHRA BR → light rain showers; mist), the same shape aviation_get_metar returns
• Forecast obscurations keep their layer and carry the vertical visibility into them (VV002 → a 200 ft indefinite ceiling), rather than reading as a clear sky
• sky_condition carries a forecast clear sky (SKC, NSC) whose group has no height to publish, so a period with no cloud element — a TEMPO or PROB group amending only visibility or weather — reads as leaving the prevailing forecast's cloud unchanged rather than as forecasting clear
• Low-level wind shear (WS020/20040KT) is decoded to the shear-layer top and the forecast wind at that height
• valid_from / valid_to in ISO 8601 for straightforward time comparisons
• Every batch reports which of the requested stations came back, so a partial result is never mistaken for full coverage — missing IDs are named with recovery guidance

---

aviation_get_pireps

Search for recent Pilot Reports by station+radius or bounding box.

• station_id + distance_nm (10–500 nm, 100 when omitted) for radial search around an airport
• bbox for geographic area search — useful for en-route corridor checks; distance_nm has no meaning here and is rejected alongside it
• altitude_min_ft / altitude_max_ft filters to isolate reports at cruise altitude, either bound alone or both (min must not exceed max). Both bounds together, spanning 6,000 ft or less, fit the API's own search width and are sent to it, so the band narrows the search rather than only trimming the result; a single bound or a wider span trims the result alone
• min_intensity (lgt / mod / sev) restricts the search to reports carrying a turbulence or icing layer at that intensity or above — it selects reports, not layers, so 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, so an icing layer always reflects something the pilot reported
• Every result states whether the upstream 400-row cap cut it, naming the levers that narrow a query before the cap applies — and only the ones the query has not already used
• limit (1–400) bounds how many reports come back without changing what is searched; it applies after the ordering by observation time, so it keeps the most recent. A limited result says so separately from the cap — a limit withheld reports that were examined, a cap dropped reports that were never drawn — and both can be reported at once without either implying the other. Selection is by recency alone, so pair it with min_intensity to bound a result by severity instead
• Note: absence of PIREPs does not mean smooth conditions — they are sparse by nature

---

aviation_get_advisories

List currently active domestic SIGMETs.

• advisory_type filter: sigmet or all (default) — both return the active SIGMET set
• hazard filter: CONVECTIVE, TURBULENCE, ICING, IFR — sent to the AWC endpoint's own hazard parameter, so the matching is done by AWC against however it spells the class
• bbox filter applied client-side (the AWC endpoint defines no bbox parameter; the tool filters by polygon overlap)
• AIRMETs are not served. The upstream feed carries domestic SIGMETs only, so advisory_type: airmet and the MTN OBSCN, SURFACE WIND, and LLWS hazards are rejected with guidance rather than answered with SIGMETs or an empty array
• During fair-weather periods, no SIGMETs may be active — an empty result is a valid state, not an error
• An empty result names what emptied it: nothing active anywhere, no advisory carrying the requested hazard, or none intersecting the requested bbox — so a filter that needs broadening is not mistaken for quiet weather

---

Prompts

Type	Name	Description
Prompt	aviation_preflight_brief	Structure a preflight weather briefing for a flight. Guides the LLM to call aviation_get_metar, aviation_get_taf, aviation_get_pireps, and aviation_get_advisories in sequence — split across as many calls as each tool's station limit requires — and synthesize a weather-risk summary with flight categories, active hazards, and the assessments it could not make.

Takes departure_icao and destination_icao, plus optional alternates, departure_time, cruise_altitude, and route_waypoints. The last three each narrow one step: the departure time selects the TAF forecast period the briefing is read against, the cruise altitude bounds the PIREP search to a ±3,000 ft band, and the route waypoints (decimal-degree lat,lon pairs) become the advisory bbox. Omit any of them and the briefing still generates, naming the assessment it could not make. It reports weather risk rather than a go/no-go recommendation — that decision needs pilot, aircraft, and operational-minima context this server does not hold.

All resource data is reachable via tools. This server has no resources — all aviation weather data is time-sensitive (METARs valid ~1 hour, advisories minutes to hours) and unsuitable for stable-URI resources.

---

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and prompt definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

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 (rawOb, rawTAF, rawAirSigmet) 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:

• Flight category (VFR/MVFR/IFR/LIFR) as a discriminated string field — agents can branch on it without parsing ceiling + visibility
• Structured error contracts with typed reason fields and recovery hints (e.g., "Verify ICAO IDs with aviation_find_stations")
• aviation_preflight_brief prompt encodes the correct METAR → TAF → PIREPs → advisories briefing sequence that agents frequently get wrong by omitting steps, chunks each step to the station limit the tool actually enforces, and names the assessments it could not make instead of implying a complete picture

---

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.3.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

Variable	Description	Default
AWC_BASE_URL	Base URL for the NWS AWC Data API.	https://aviationweather.gov/api/data
AWC_TIMEOUT_MS	Per-request timeout in milliseconds (1000–60000).	10000
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	Port for HTTP server.	3010
MCP_SESSION_MODE	HTTP session handling: auto (resolves to stateful), stateful, or stateless. The shipped .env.example and Docker image pin stateless — no tool here needs a multi-round-trip input.	stateless
MCP_AUTH_MODE	Auth mode: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (RFC 5424).	info
OTEL_ENABLED	Enable OpenTelemetry instrumentation.	false

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

Directory	Purpose
src/index.ts	createApp() entry point — registers tools/prompts and inits services.
src/config	Server-specific env var parsing (AWC_BASE_URL, AWC_TIMEOUT_MS).
src/services/aviation-weather	AWC Data API client — HTTP fetch, retry with exponential backoff, response normalization.
src/mcp-server/tools	Tool definitions (*.tool.ts).
src/mcp-server/prompts	Prompt definitions (*.prompt.ts).
tests/	Unit and integration tests mirroring src/.

---

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 via the barrels in src/mcp-server/*/definitions/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 and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

---

License

Apache-2.0 — see LICENSE for details.