io.github.cyanheads/aviation-weather-mcp-server

Official5 toolsLive

by cyanheads · TypeScript

Fetch METARs, TAFs, PIREPs, and domestic SIGMETs from the NWS Aviation Weather Center.

This Model Context Protocol (MCP) server fetches aviation weather data—specifically METARs, TAFs, PIREPs, and domestic SIGMETs—from the NWS Aviation Weather Center via MCP. It supports communication over STDIO or Streamable HTTP.

🛠️ Key Features

MCP server for aviation weather retrieval
Data sources: NWS Aviation Weather Center
Fetches METARs, TAFs, PIREPs, and domestic SIGMETs
5 tools (toolCount)

🚀 Use Cases

Query current METAR conditions
Retrieve forecast TAFs
Incorporate PIREPs observations
Access domestic SIGMET information

⚡ Developer Benefits

Works within Model Context Protocol workflows
Integrates using STDIO or Streamable HTTP
Repository topics include TypeScript, MCP, and aviation-weather

⚠️ Limitations

Limited to NWS Aviation Weather Center content: METARs, TAFs, PIREPs, and domestic SIGMETs

Topics

ai-agentsai-toolsaviationaviation-weathercyanheadsmcpmcp-servermetarmodel-context-protocolnoaataftypescript

Captured live from the server via tools/list.

aviation_find_stations

Resolve an airport or weather reporting station by its identifier, or discover stations within a bounding box or US state. Returns all identifier variants (ICAO/IATA/FAA), coordinates, elevation, and available data types (METAR, TAF, SYNOP, etc.). A lookup matches the registry's own identifier, which for an airport is its 4-character ICAO ID (e.g., KSEA, KJFK, K0S9); buoys and mesonet sites carry identifiers of other shapes and resolve by those. At least one of station_ids, bbox, or state is required. limit bounds how many stations an area search returns without changing the area searched, and belongs to the bbox and state modes only.

Parameters4

station_ids	array	optional	One or more station identifiers (e.g., KSEA, KJFK). A lookup matches the registry's own identifier: a 4-character ICAO ID for an airport (e.g., KSEA, K0S9), and other shapes for the buoys and mesonet sites the registry also carries, which resolve by those. A 3-letter IATA code (e.g., SEA) never resolves, even for a station whose entry carries one. Whitespace around an entry is trimmed, so a padded identifier resolves the same as the bare one; an empty or whitespace-only entry is rejected. Use bbox or state to discover identifiers by location.
bbox	object	optional	Geographic bounding box for spatial queries.
state	string	optional	Two-letter USPS code for one of the 50 US states or DC (e.g., "WA") to list all stations in that jurisdiction. US territories are not supported — use bbox for those.
limit	integer	optional	Maximum stations to return, applied after ordering by ICAO identifier ascending with identifier-less stations last — so the same query with the same limit returns the same stations, and airports rather than unidentified sites lead the first page. It bounds the response without changing the area searched, which a smaller bbox or a different state would. Distinct from the 400-row upstream cap: a limited result examined every station it counted and withheld some, while a capped one never drew the rest. Belongs to the bbox and state modes; supplying it alongside station_ids is rejected, since that mode already names the set. Omit to return every match. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "station_ids": {
      "description": "One or more station identifiers (e.g., KSEA, KJFK). A lookup matches the registry's own identifier: a 4-character ICAO ID for an airport (e.g., KSEA, K0S9), and other shapes for the buoys and mesonet sites the registry also carries, which resolve by those. A 3-letter IATA code (e.g., SEA) never resolves, even for a station whose entry carries one. Whitespace around an entry is trimmed, so a padded identifier resolves the same as the bare one; an empty or whitespace-only entry is rejected. Use bbox or state to discover identifiers by location.",
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "\\S",
        "description": "One station identifier (e.g., KSEA)."
      }
    },
    "bbox": {
      "type": "object",
      "properties": {
        "minLat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Southern boundary latitude in decimal degrees."
        },
        "minLon": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Western boundary longitude in decimal degrees."
        },
        "maxLat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Northern boundary latitude in decimal degrees."
        },
        "maxLon": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Eastern boundary longitude in decimal degrees."
        }
      },
      "required": [
        "minLat",
        "minLon",
        "maxLat",
        "maxLon"
      ],
      "description": "Geographic bounding box for spatial queries."
    },
    "state": {
      "description": "Two-letter USPS code for one of the 50 US states or DC (e.g., \"WA\") to list all stations in that jurisdiction. US territories are not supported — use bbox for those.",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "limit": {
      "description": "Maximum stations to return, applied after ordering by ICAO identifier ascending with identifier-less stations last — so the same query with the same limit returns the same stations, and airports rather than unidentified sites lead the first page. It bounds the response without changing the area searched, which a smaller bbox or a different state would. Distinct from the 400-row upstream cap: a limited result examined every station it counted and withheld some, while a capped one never drew the rest. Belongs to the bbox and state modes; supplying it alongside station_ids is rejected, since that mode already names the set. Omit to return every match. Optional.",
      "type": "integer",
      "minimum": 1,
      "maximum": 400
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

aviation_get_metar

Get current weather observations (METARs) for named airports, or survey every reporting station inside a geographic area. Returns decoded fields — wind direction/speed/gusts, visibility, ceiling with its kind (measured, or indefinite for vertical visibility into an obscuration), present weather, temperature, dewpoint, altimeter, cloud layers — plus the computed flight category (VFR/MVFR/IFR/LIFR) and the raw METAR string. Requires either station_ids (1–10 ICAO IDs, e.g., KSEA, KJFK, K0S9) or bbox (area survey) — not both. station_ids returns every observation inside the hours window; bbox returns the latest observation per station in the box, with flight_category keeping only the stations in the categories named (e.g., IFR and LIFR) and limit bounding how many stations come back. Use aviation_find_stations to resolve or verify an ICAO ID, or to discover nearby stations.

Parameters5

station_ids	array	optional	ICAO station IDs to query. 1–10 stations per call, and every observation inside the hours window is returned for each. Supplying it alongside bbox is rejected — use bbox to ask about an area rather than a named set.
bbox	object	optional	Geographic bounding box for an area observation survey.
hours	integer	optional	Lookback window in hours (1–12), not a row limit. With station_ids every observation inside the window is returned, so a station reporting more often than hourly yields more than one row per hour: at the default of 1, half-hourly stations return two observations and SPECI-issuing stations can return more, so budget rows by the station reporting interval, never one per station. With bbox the result is reduced to the latest observation per station, but the window still shapes the draw the upstream row cap applies to — a wide window spends that cap on repeat readings from busy stations instead of on more stations, so lower it before narrowing the box.
limit	integer	optional	Maximum stations to return, applied after the draw is reduced to the latest observation per station, after any flight_category filter, and ordered by station ID ascending — so the same query with the same limit returns the same stations. It bounds the response without changing the area searched, which a smaller bbox would, and it keeps an alphabetical slice rather than a region or a condition. Distinct from the 400-row upstream cap: a limited result examined every station it counted and withheld some, while a capped one never drew the rest. Belongs to the bbox mode; supplying it alongside station_ids is rejected, since that mode already names the set. Omit to return every station in the box. Optional.
flight_category	array	optional	Return only the stations whose flight category is one of these (e.g., ["IFR", "LIFR"] to find where conditions are poor). Applied in the tool after the draw is reduced to the latest observation per station and before limit, so it changes which stations come back, not what AWC draws or the upstream row cap. A station AWC could not rate (flight_category "unknown") never matches. Belongs to the bbox mode; supplying it alongside station_ids is rejected, since each named station already reports its own category. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "station_ids": {
      "description": "ICAO station IDs to query. 1–10 stations per call, and every observation inside the hours window is returned for each. Supplying it alongside bbox is rejected — use bbox to ask about an area rather than a named set.",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Z0-9]{4}$",
        "description": "ICAO station ID: 4 uppercase letters or digits (e.g., KSEA, KJFK, K0S9)."
      }
    },
    "bbox": {
      "type": "object",
      "properties": {
        "minLat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Southern boundary latitude in decimal degrees."
        },
        "minLon": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Western boundary longitude in decimal degrees."
        },
        "maxLat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Northern boundary latitude in decimal degrees."
        },
        "maxLon": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Eastern boundary longitude in decimal degrees."
        }
      },
      "required": [
        "minLat",
        "minLon",
        "maxLat",
        "maxLon"
      ],
      "description": "Geographic bounding box for an area observation survey."
    },
    "hours": {
      "default": 1,
      "description": "Lookback window in hours (1–12), not a row limit. With station_ids every observation inside the window is returned, so a station reporting more often than hourly yields more than one row per hour: at the default of 1, half-hourly stations return two observations and SPECI-issuing stations can return more, so budget rows by the station reporting interval, never one per station. With bbox the result is reduced to the latest observation per station, but the window still shapes the draw the upstream row cap applies to — a wide window spends that cap on repeat readings from busy stations instead of on more stations, so lower it before narrowing the box.",
      "type": "integer",
      "minimum": 1,
      "maximum": 12
    },
    "limit": {
      "description": "Maximum stations to return, applied after the draw is reduced to the latest observation per station, after any flight_category filter, and ordered by station ID ascending — so the same query with the same limit returns the same stations. It bounds the response without changing the area searched, which a smaller bbox would, and it keeps an alphabetical slice rather than a region or a condition. Distinct from the 400-row upstream cap: a limited result examined every station it counted and withheld some, while a capped one never drew the rest. Belongs to the bbox mode; supplying it alongside station_ids is rejected, since that mode already names the set. Omit to return every station in the box. Optional.",
      "type": "integer",
      "minimum": 1,
      "maximum": 400
    },
    "flight_category": {
      "description": "Return only the stations whose flight category is one of these (e.g., [\"IFR\", \"LIFR\"] to find where conditions are poor). Applied in the tool after the draw is reduced to the latest observation per station and before limit, so it changes which stations come back, not what AWC draws or the upstream row cap. A station AWC could not rate (flight_category \"unknown\") never matches. Belongs to the bbox mode; supplying it alongside station_ids is rejected, since each named station already reports its own category. Optional.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "VFR",
          "MVFR",
          "IFR",
          "LIFR"
        ],
        "description": "A flight category: VFR, MVFR, IFR, or LIFR."
      }
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

aviation_get_taf

Get the Terminal Aerodrome Forecast (TAF) for one or more airports. Returns each forecast period with valid times, surface wind, low-level wind shear, visibility, decoded weather conditions, cloud layers, and the vertical visibility into a forecast obscuration, plus the raw TAF string. TAFs cover the next 24–30 hours and are issued only for airports with scheduled commercial service; check data_types from aviation_find_stations to confirm TAF availability. Accepts 1–4 ICAO station IDs (e.g., KSEA, KJFK, K36U).

Parameters1

station_ids

array

required

ICAO station IDs to query. 1–4 stations per call.

Raw schema

{
  "type": "object",
  "properties": {
    "station_ids": {
      "minItems": 1,
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Z0-9]{4}$",
        "description": "ICAO station ID: 4 uppercase letters or digits (e.g., KSEA, KJFK, K36U)."
      },
      "description": "ICAO station IDs to query. 1–4 stations per call."
    }
  },
  "required": [
    "station_ids"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

aviation_get_pireps

Get recent Pilot Reports (PIREPs) near an airport or within a bounding box. Returns decoded turbulence, icing, and cloud reports with altitude, aircraft type, intensity, outside air temperature, wind aloft, flight weather, and the raw PIREP string. Requires either station_id (ICAO center point for radial search, e.g., KSEA) or bbox (area search) — not both. distance_nm belongs to the station_id search only, and altitude_min_ft must not exceed altitude_max_ft. min_intensity restricts the result to reports carrying a turbulence or icing layer at that intensity or above. limit bounds how many reports come back without changing what is searched, keeping the most recent. Coverage is US-centric; PIREPs are sparse and absence of reports does not imply smooth conditions.

Parameters8

station_id	string	optional	ICAO station ID as center point for radial search — 4 uppercase letters or digits (e.g., KSEA, K0S9). Use with distance_nm.
bbox	object	optional	Geographic bounding box for area PIREP search.
distance_nm	integer	optional	Search radius in nautical miles around station_id, defaulting to 100 when omitted. Belongs to the station_id search only — supplying it alongside bbox is rejected.
hours	integer	optional	How many hours of history to return. Default 3.
altitude_min_ft	integer	optional	Filter by minimum altitude in feet MSL (e.g., 18000 for FL180), from 0 to 60000 ft — AWC searches no band below sea level, and none centred above FL600, which is already above the altitude any pilot report carries. Reports with an unknown altitude (altitude_ft null) cannot be shown to satisfy a bound and are dropped whenever either bound is set. Optional.
altitude_max_ft	integer	optional	Filter by maximum altitude in feet MSL (e.g., 35000 for FL350), from 0 to 60000 ft — AWC searches no band below sea level, and none centred above FL600, which is already above the altitude any pilot report carries. Reports with an unknown altitude (altitude_ft null) cannot be shown to satisfy a bound and are dropped whenever either bound is set. Optional.
min_intensity	string	optional	Return only reports carrying at least one turbulence or icing layer at this intensity or above. The filter selects reports, not layers — a matching report still carries its lighter layers, so a result may include NEG, TRC, or LGT entries alongside the layer that matched. Optional.
limit	integer	optional	Maximum reports to return, applied last — after every filter and after ordering by observation time descending, so a limited result is the most recent reports rather than an arbitrary slice. It bounds the response without changing what is searched, which every other parameter does. Distinct from the 400-row upstream cap: a limited result examined every report it counted and withheld some, while a capped one never drew the rest. Selection is by recency alone, so pair it with min_intensity to bound a result by severity. Omit to return every match. Optional.

Raw schema

{
  "type": "object",
  "properties": {
    "station_id": {
      "description": "ICAO station ID as center point for radial search — 4 uppercase letters or digits (e.g., KSEA, K0S9). Use with distance_nm.",
      "type": "string",
      "pattern": "^[A-Z0-9]{4}$"
    },
    "bbox": {
      "type": "object",
      "properties": {
        "minLat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Southern boundary latitude in decimal degrees."
        },
        "minLon": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Western boundary longitude in decimal degrees."
        },
        "maxLat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Northern boundary latitude in decimal degrees."
        },
        "maxLon": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Eastern boundary longitude in decimal degrees."
        }
      },
      "required": [
        "minLat",
        "minLon",
        "maxLat",
        "maxLon"
      ],
      "description": "Geographic bounding box for area PIREP search."
    },
    "distance_nm": {
      "description": "Search radius in nautical miles around station_id, defaulting to 100 when omitted. Belongs to the station_id search only — supplying it alongside bbox is rejected.",
      "type": "integer",
      "minimum": 10,
      "maximum": 500
    },
    "hours": {
      "default": 3,
      "description": "How many hours of history to return. Default 3.",
      "type": "integer",
      "minimum": 1,
      "maximum": 12
    },
    "altitude_min_ft": {
      "description": "Filter by minimum altitude in feet MSL (e.g., 18000 for FL180), from 0 to 60000 ft — AWC searches no band below sea level, and none centred above FL600, which is already above the altitude any pilot report carries. Reports with an unknown altitude (altitude_ft null) cannot be shown to satisfy a bound and are dropped whenever either bound is set. Optional.",
      "type": "integer",
      "minimum": 0,
      "maximum": 60000
    },
    "altitude_max_ft": {
      "description": "Filter by maximum altitude in feet MSL (e.g., 35000 for FL350), from 0 to 60000 ft — AWC searches no band below sea level, and none centred above FL600, which is already above the altitude any pilot report carries. Reports with an unknown altitude (altitude_ft null) cannot be shown to satisfy a bound and are dropped whenever either bound is set. Optional.",
      "type": "integer",
      "minimum": 0,
      "maximum": 60000
    },
    "min_intensity": {
      "description": "Return only reports carrying at least one turbulence or icing layer at this intensity or above. The filter selects reports, not layers — a matching report still carries its lighter layers, so a result may include NEG, TRC, or LGT entries alongside the layer that matched. Optional.",
      "type": "string",
      "enum": [
        "lgt",
        "mod",
        "sev"
      ]
    },
    "limit": {
      "description": "Maximum reports to return, applied last — after every filter and after ordering by observation time descending, so a limited result is the most recent reports rather than an arbitrary slice. It bounds the response without changing what is searched, which every other parameter does. Distinct from the 400-row upstream cap: a limited result examined every report it counted and withheld some, while a capped one never drew the rest. Selection is by recency alone, so pair it with min_intensity to bound a result by severity. Omit to return every match. Optional.",
      "type": "integer",
      "minimum": 1,
      "maximum": 400
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

aviation_get_advisories

Get active domestic SIGMETs for a region. Returns each advisory with hazard type (CONVECTIVE, TURBULENCE, ICING, IFR), severity, altitude range, valid period, polygon coordinates, and raw text. Coverage is US-centric (NWS Aviation Weather Center). This tool reads the domestic SIGMET feed only and cannot return an AIRMET; requests for one are rejected rather than answered with SIGMETs. During fair-weather periods no advisories may be active — an empty result is normal, not an error. Filter by advisory_type, hazard, or bbox.

Parameters3

advisory_type	string	optional	Filter by advisory type. "sigmet" and "all" both return the active domestic SIGMET set, which is everything this tool serves. "airmet" is rejected with guidance: the upstream feed cannot return an AIRMET, so answering it would mean presenting SIGMETs as AIRMET matches.
hazard	string	optional	Optional hazard filter, applied upstream by AWC. CONVECTIVE, TURBULENCE, ICING, and IFR are the four hazard classes the domestic SIGMET feed carries, and an empty result under one of them means no advisory of that class is active — it says nothing about the others. MTN OBSCN, SURFACE WIND, and LLWS are AIRMET-family phenomena with no upstream counterpart here and are rejected rather than returning an empty result.
bbox	object	optional	Geographic bounding box to filter advisories by polygon overlap.

Raw schema

{
  "type": "object",
  "properties": {
    "advisory_type": {
      "default": "all",
      "description": "Filter by advisory type. \"sigmet\" and \"all\" both return the active domestic SIGMET set, which is everything this tool serves. \"airmet\" is rejected with guidance: the upstream feed cannot return an AIRMET, so answering it would mean presenting SIGMETs as AIRMET matches.",
      "type": "string",
      "enum": [
        "sigmet",
        "airmet",
        "all"
      ]
    },
    "hazard": {
      "description": "Optional hazard filter, applied upstream by AWC. CONVECTIVE, TURBULENCE, ICING, and IFR are the four hazard classes the domestic SIGMET feed carries, and an empty result under one of them means no advisory of that class is active — it says nothing about the others. MTN OBSCN, SURFACE WIND, and LLWS are AIRMET-family phenomena with no upstream counterpart here and are rejected rather than returning an empty result.",
      "type": "string",
      "enum": [
        "CONVECTIVE",
        "TURBULENCE",
        "ICING",
        "IFR",
        "MTN OBSCN",
        "SURFACE WIND",
        "LLWS"
      ]
    },
    "bbox": {
      "type": "object",
      "properties": {
        "minLat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Southern boundary latitude in decimal degrees."
        },
        "minLon": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Western boundary longitude in decimal degrees."
        },
        "maxLat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90,
          "description": "Northern boundary latitude in decimal degrees."
        },
        "maxLon": {
          "type": "number",
          "minimum": -180,
          "maximum": 180,
          "description": "Eastern boundary longitude in decimal degrees."
        }
      },
      "required": [
        "minLat",
        "minLon",
        "maxLat",
        "maxLon"
      ],
      "description": "Geographic bounding box to filter advisories by polygon overlap."
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md18 KBView on GitHub

@cyanheads/aviation-weather-mcp-server

Fetch METARs, TAFs, PIREPs, and domestic SIGMETs from the NWS Aviation Weather Center via MCP. STDIO or Streamable HTTP.

5 Tools • 1 Prompt

Version MCP SDK TypeScript

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

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 named airports, or survey every reporting station in a bounding box. 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, outside air temperature, wind aloft, flight weather, 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.

Prompts

Prompt	Description
`aviation_preflight_brief`	Structure a preflight weather briefing for a flight, calling the tools above in sequence and synthesizing a weather-risk summary.

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:

json

{
  "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.

json

{
  "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):

json

{
  "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:

json

{
  "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

Clone the repository:

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

Navigate into the directory:

cd aviation-weather-mcp-server

Install dependencies:

bun install

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 server declares `stateless` in code — no tool here needs a multi-round-trip input — and the shipped `.env.example` and Docker image pin the same value. Setting this overrides the declaration.	`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 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.

Install

Tools (5)

aviation_find_stationsaviation_get_metaraviation_get_tafaviation_get_pirepsaviation_get_advisories

Configuration

Environment variables

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

AWC_BASE_URLdefault https://aviationweather.gov/api/data

Base URL for the AWC Data API. Useful for testing against a mock or staging instance.

AWC_TIMEOUT_MSdefault 10000

Per-request timeout in milliseconds (1000–60000).

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "aviation-weather-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/aviation-weather-mcp-server@0.5.0",
        "run",
        "start:stdio"
      ],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "AWC_BASE_URL": "https://aviationweather.gov/api/data",
        "AWC_TIMEOUT_MS": "10000"
      }
    }
  }
}

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

aviation_find_stations

aviation_get_metar

aviation_get_taf

aviation_get_pireps

aviation_get_advisories

@cyanheads/aviation-weather-mcp-server

Overview

Tools

Prompts

Capability reference

aviation_find_stations tool

aviation_get_metar tool

aviation_get_taf tool

aviation_get_pireps tool

aviation_get_advisories tool

aviation_preflight_brief prompt

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`aviation_find_stations` _tool

`aviation_get_metar` _tool

`aviation_get_taf` _tool

`aviation_get_pireps` _tool

`aviation_get_advisories` _tool

`aviation_preflight_brief` _prompt