@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, domestic/international SIGMETs, and Center Weather Advisories. Look up stations, fetch current and forecast conditions, and pull pilot reports and hazard advisories. AIRMETs are not served.
Tools
Tool | Description |
| Resolve airports and weather stations by identifier, bounding box, or US state. Returns ICAO/IATA/FAA IDs, coordinates, elevation, and available data types. |
| Get current or historical observations for named airports, a bounding box, or a US state. Returns decoded conditions, flight category, and the raw METAR. |
| Get current or historically issued forecasts for named airports, a bounding box, or a US state. Returns decoded forecast periods and the raw TAF. |
| Get current or historical pilot reports near an airport or within a bounding box. Returns decoded conditions aloft, aircraft type, and the raw report. |
| Get domestic/international SIGMETs and Center Weather Advisories. Returns source coverage, hazard, severity, altitude, validity, movement, multipart geometry and original bulletins; omitted facts stay null. |
Prompts
Prompt | Description |
| Structure a preflight weather briefing for a flight, calling the tools above in sequence and synthesizing a weather-risk summary. |
Resources
Resource | Description |
| Aviation weather guide for regional surveys, airport comparisons, and route assessments, with station identity, forecast timing, and incomplete coverage reconciled before drawing conclusions. |
Related MCP server: mcp-metar
Capability reference
METARs, TAFs and PIREPs accept an optional UTC as_of timestamp within the past 30 days. Use YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss.sssZ. Omit the anchor for a current lookup.
Area METAR and TAF surveys, PIREPs, area station searches and advisories accept a zero-based offset and optional limit. Repeat the same query with the returned nextOffset to continue. Each call uses the currently available draw, which may change between pages. Paging cannot recover rows AWC withheld. Omitting limit returns every remaining match. Explicit limits above 400 are clamped with a notice on METAR and TAF surveys, PIREPs and area station searches. Set AWC_CLAMP_LIMITS=false to reject them.
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 availableDiscover 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 queryingA
bboxsearch reports when the draw reaches AWC's 400-row cap. Station pages order by ICAO identifier with identifier-less sites last. Named lookups rejectoffsetandlimit.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
Comma-separated entries are split and each token trimmed once; the expanded list must contain 1–20 identifiers, with no empty tokens
State searches select US registry membership from a complete station snapshot refreshed on demand after 24 hours, including offshore and eastern-longitude Alaska records. Expired snapshots are never served after a failed refresh; retry or use
bbox/station_ids. Geographic searches retain the stationinfo endpoint and its row capNamed lookups also return nullable
magnetic_declination: signed degrees (east positive) and exact source text from one supplementary airport batch. Unrecognized syntax keeps the text with unknown degrees. Missing airport data and area searches return null; a failed supplementary request adds a notice while preserving station results. This is published variation without an epoch, not a current geomagnetic model or a correction for every PIREP location
aviation_get_metar tool
Choose one of
station_ids(1–10 ICAO IDs),bbox, orstate(a two-letter US state or DC code). Surveys report the latest drawn observation per station, ordered by station ID. Named lookups return every observation drawn and reject survey filters and paging.hoursis a 1–720 hour lookback ending atas_ofor the current time. It defaults to one hour.flight_category(for example,["IFR", "LIFR"]) filters a survey by each station's latest observation before paging. Unrated observations never match. An empty filtered survey reports the count it examined.Either mode can reach the upstream 400-row cap. Shorten the lookback or use successive earlier anchors to recover separate time windows. For bbox surveys, smaller boxes can recover geographic omissions. Treat missing named stations as unresolved when the draw is capped.
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_conditiondistinguishes a reported clear sky from an unreported one whencloudsis emptymetar_typedistinguishes routineMETARfrom specialSPECIobservationsEvery batch reports which requested stations came back, naming missing IDs with recovery guidance
aviation_get_taf tool
Choose one of
station_ids(1–4 ICAO IDs),bbox, orstate(a two-letter US state or DC code). Search a nearby bbox if a named airport has no forecast. Named lookups reject paging.METAR and TAF state surveys use AWC's weather selector. Use
aviation_find_stationsfor state registry membership.An anchored lookup requests AWC's selection by issuance time. The selected forecast can start after the anchor. Check
valid_fromandvalid_tobefore interpreting its periods.Structured periods preserve change groups and probabilities.
transition_endis when a BECMG transition is expected to finish. Decoded fields include altimeter pressure in hPa, separately timed temperature extrema, and icing/turbulence layers with their source intensity codes and available altitude bounds.Each forecast includes source remarks.
amendedis true for an AMD header marker, false for a recognized header without it, and null when the header cannot be classified.Forecast obscurations keep their layer and carry the vertical visibility into them, rather than reading as clear sky;
sky_conditiondistinguishes an unamended period from a stated clear skyText the upstream decoder left undecoded — often a fourth cloud layer — is surfaced per period in
not_decodedrather than droppedLow-level wind shear (
WS020/20040KT) decoded to the shear-layer top and forecast wind at that heightvalid_from/valid_toin ISO 8601 for time comparisonsEvery batch reports which requested stations came back, naming missing IDs with recovery guidance
aviation_get_pireps tool
station_id(4 ASCII letters or digits in either case, normalized to uppercase) +distance_nm(10–500 nm, 100 when omitted) for radial search, orbboxfor area search — mutually exclusive; astation_idAWC does not recognize as a search center returns a typed error pointing toaviation_find_stationsorbboxhoursis a 1–48 hour lookback ending atas_ofor the current time. It defaults to three hours.Resolved station searches select a true nautical-mile circle from enclosing candidates, splitting antimeridian envelopes into two draws. Missing coordinates or an unavailable coordinate lookup retain the legacy AWC search with an explicit unverified-radius notice; use
bboxfor explicit geographic boundsaltitude_min_ft/altitude_max_ftfilter 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 setmin_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 layersTurbulence and icing arrays include up to two layers per report; icing layers the API synthesized for a report that never mentioned ice are dropped
Source report types remain open strings, including
PIREP,Urgent PIREP,AIREP, andAMDAR. Outside air temperature (temp_c), wind aloft (wind), and decoded/WXflight weather (weather) preserve available readings. Ordinary and urgent PIREP wind directions are magnetic and unconverted; other report types receive no unverified reference labelNullable
braking_actionpreserves AWC's decodedbrkAction(e.g.,MED), including unfamiliar codes, without parsing remarks or inferring runway conditionsEvery result states whether any candidate draw reached the upstream 400-row cap before radius and altitude filtering. Capped draws remain partial even when filtering leaves no reports. Pages start with the most recent matching reports.
PIREPs are sparse by nature — absence of reports does not mean smooth conditions
aviation_get_advisories tool
advisory_type:sigmet(domestic),isigmet(international, including oceanic),cwa(Center Weather Advisories), orall(default: all three independent products)hazardis applied upstream:TSandCONVECTIVEare thunderstorm aliases for every product. Domestic also supportsTURBULENCE,ICING,IFR; international also supportsTURBULENCE,ICING,MTW,DS,SS,TC,VA; CWA also supportsTURBULENCE,ICING,IFR,PCPN,UNK. Output hazards stay source-native. Incompatible sources arenot_applicable; a selection with no compatible source is rejectedcoveragereports each selected source asok,failedornot_applicable, with decoded drawn counts only for readable sources.partialmarks failed sources or skipped unreadable rows. Independent healthy products survive a failure; all applicable products failing is an error. One 45-second deadline bounds the concurrent advisory reads and retries; caller cancellation aborts all legsaltitude_ftoptionally selects a cruise altitude in nonnegative finite feet MSL. It rounds to the nearest 100 ft (half steps upward) and echoesaltitude_selection: requested feet, effective integer flight level, and ±3,000 ft band with lower edge clamped to zero. SIGMET products use AWC's documentedlevel; CWA uses inclusive interval overlap locally. Either unknown CWA bound retains the row conservatively. Per-sourcealtitude_filteridentifiesupstreamorclient;altitude_unknowncounts retained unknown bounds before bbox, describing only returned upstream data, not proven altitude matches. Both are null without an altitude filter or available coverageCWA cancellation notices are excluded before active counts;
coverage[].cancelleddiscloses their number (zero on readable feeds with none, null when unavailable). Cancellation and unknown altitude alone do not make coverage partialbboxuses each intact geometry part's bounding envelope, including date-line crossings, rather than exact polygon intersection. Finite extended source longitudes wrap into [-180,180]; canonical coordinates remain unchanged. Input remains ordered (minLat <= maxLat,minLon <= maxLon). With bbox,drawncounts rows after cancellation removal and product/hazard/altitude selection,matchedcounts geographic matches,returnedcounts rows after any limit, andunlocatedseparately counts rows without decoded geometryPages order by source, issuer, series, validity and bulletin text.
total,returnedandtruncateddescribe paging over the available matches. Advisory limits have no automatic 400-row clamp.Missing issuer, series, hazard, validity and raw text stay null.
geometry.partspreserves separate rings/lines and source-nativekind(including null); compatibilitypolygonis null for multipart, line or missing geometry. Domestic numeric severity/movement stay source-native; finite primary altitude bounds precede alternate bounds. International movement preservesdirection_text(including-) and decoded knots on one line; nullablestationaryis true only for explicit unquoted standaloneSTNR, false for a non-sentinel direction with positive speed, otherwise null. Internationaltendencyand CWAissued_by_nameretain source tokens/names or null. CWA severity/movement remain null, and altitudes are never inferred from bulletin textOriginal bulletins render in safe code fences preserving blank lines and embedded backticks. An empty result names readable sources and filtering stage; unavailable sources never establish fair weather
AIRMETs are not served. Requests for one (or
MTN OBSCN/SURFACE WIND/LLWS) are rejected with guidance to separate AIRMET products
aviation_preflight_brief prompt
Arguments:
departure_icaoanddestination_icaorequired;alternates(comma-separated ICAOs),departure_time(ISO 8601 UTC),cruise_altitude(feet MSL), androute_waypoints(semicolon-separatedlat,lonpairs) optionalEvery ICAO argument accepts 4 ASCII letters or digits in either case and generates uppercase IDs. For an IATA/FAA code, use
aviation_find_stationswithstateorbboxto find the ICAO ID; no mapping is inferred. Direct IDs reject surrounding whitespace; comma-separated alternates allow itCalls
aviation_get_metar,aviation_get_taf,aviation_get_pireps, andaviation_get_advisoriesin sequence, chunked to each tool's station-per-call limitdeparture_timesets the time to compare against TAF validity, prevailing conditions, BECMG transitions and active TEMPO or PROB overlays.The prompt requests PIREPs and advisories per route box, splitting at the date line where needed. Without waypoints, it builds an airport-based approximation from METAR positions when both endpoints are located. If an endpoint is unlocated, it retains separate endpoint PIREP searches and reports the missing advisory area assessment.
cruise_altitudesets a ±3,000 ft PIREP band and forwardsaltitude_ftto advisory calls, including explicit zero.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 endpointRaw coded strings (
raw_metar,raw_taf,raw_pirep,raw_text) surfaced alongside decoded fields so agents have both layersComplete in-memory station registry snapshots provide US-state membership without geographic approximations
Server-level
instructionsfield surfaces the "not an official briefing" safety disclaimer to all clients oninitialize
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 visibilityStructured error contracts — typed
reasonfields withrecoveryhints (e.g., "Verify ICAO IDs withaviation_find_stations")Partial-result reconciliation — batch tools report
requested/returned/missing/partialfields, so a short batch is never mistaken for full coverageWorkflow sequencing — the
aviation_preflight_briefprompt 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/mcpPrerequisites
Bun v1.4.4 or higher (or Node.js v24+).
No API key required — the AWC Data API is fully public and keyless.
Installation
Clone the repository:
git clone https://github.com/cyanheads/aviation-weather-mcp-server.gitNavigate into the directory:
cd aviation-weather-mcp-serverInstall dependencies:
bun installConfigure environment:
cp .env.example .env
# edit .env to override AWC settingsConfiguration
Variable | Description | Default |
| Base URL for the NWS AWC Data API. |
|
| Per-request timeout in milliseconds (1000–60000). |
|
| Clamp explicit result limits above 400. Set to |
|
| Transport: |
|
| Port for HTTP server. |
|
| HTTP session handling: |
|
| Auth mode: |
|
| Log level (RFC 5424). |
|
| Enable OpenTelemetry instrumentation. |
|
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:httpRun 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-serverThe 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 |
|
|
| AWC URL, timeout and result-limit configuration. |
| AWC Data API client — HTTP fetch, retry with exponential backoff, response normalization. |
| Tool definitions ( |
| Prompt definitions ( |
| Published assessment guide, available through MCP as |
| Unit and integration tests mirroring |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storageRegister new tools and prompts in the
createApp()arrays insrc/index.tsWrap 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
instructionsfield sent on everyinitialize.
Contributing
Issues are welcome. Run checks and tests before submitting:
bun run devcheck
bun run testLicense
Apache-2.0 — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Aviation Weather MCP — METAR, TAF, PIREPs, AIRMET/SIGMET, station info
Hosted MCP server for Xweather weather data: conditions, forecasts, alerts, and more.
Unofficial FlightAware MCP — wraps FlightAware AeroAPI v4 (aeroapi.flightaware.com)
NOAA and ECMWF weather forecast MCP for discovery, validation, and GribStream OAuth queries.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides aviation weather information through a Model Context Protocol server, enabling access to METARs, TAFs, PIREPs, and route weather data for informational purposes only.2MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for fetching METAR and TAF aviation weather data for airports by ICAO code.MIT
- FlicenseNot gradedqualityDmaintenanceFetches and parses METAR/TAF aviation weather data from NOAA with caching and human-readable formatting.1-
- AlicenseNot gradedqualityCmaintenanceMCP server providing real-time aviation weather data (METAR, TAF, PIREPs, AIRMETs) from aviationweather.gov for flight planning and analysis.22 npmMIT