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

Official9 toolsLive

by cyanheads · TypeScript

Get US weather forecasts, active alerts, and current observations.

@cyanheads/nws-weather-mcp-server

The Model Context Protocol (MCP) server io.github.cyanheads/nws-weather-mcp-server provides US weather data from the National Weather Service API. It returns weather forecasts, active alerts, and current observations. Connectivity is available via STDIO or Streamable HTTP, with 7 tools exposed by the server.

🛠️ Key Features

US weather forecasts
Active alerts
Current observations
National Weather Service API integration
7 tools available
Access via STDIO or Streamable HTTP

🚀 Use Cases

Fetch current observation conditions
Check active alerts for affected areas
Retrieve forecast information from NWS

⚡ Developer Benefits

MCP-compatible weather tooling
Uses Model Context Protocol with TypeScript
Tooling focused on alerts, forecast, and observations

⚠️ Limitations

Provides US weather data via the National Weather Service API only
Documented details beyond tool count, name/description, and transport options are limited

Topics

alertsforecastmcpmcp-servermodel-context-protocolnational-weather-servicenwstypescriptweatherobservationscyanheads

Captured live from the server via tools/list.

nws_get_forecast

Get the weather forecast for a US location. Returns either named 12-hour periods (default) or hourly breakdowns.

Parameters4

latitude	number	required	Latitude in decimal degrees (e.g., 47.6062).
longitude	number	required	Longitude in decimal degrees (e.g., -122.3321).
hourly	boolean	optional	If true, returns hourly forecast (48 one-hour periods per page, ~156 available) instead of 12-hour named periods (14 periods). Hourly includes dewpoint and relative humidity.
cursor	string	optional	Opaque continuation token from a previous response's nextCursor, to retrieve the next 48 periods. Omit for the first page. Every call re-fetches the forecast, so consecutive periods are contiguous within one response; NWS reissues forecasts through the day, so a later call can window a regenerated period array.

Raw schema

{
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Latitude in decimal degrees (e.g., 47.6062)."
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "Longitude in decimal degrees (e.g., -122.3321)."
    },
    "hourly": {
      "default": false,
      "description": "If true, returns hourly forecast (48 one-hour periods per page, ~156 available) instead of 12-hour named periods (14 periods). Hourly includes dewpoint and relative humidity.",
      "type": "boolean"
    },
    "cursor": {
      "description": "Opaque continuation token from a previous response's nextCursor, to retrieve the next 48 periods. Omit for the first page. Every call re-fetches the forecast, so consecutive periods are contiguous within one response; NWS reissues forecasts through the day, so a later call can window a regenerated period array.",
      "type": "string"
    }
  },
  "required": [
    "latitude",
    "longitude"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

nws_search_alerts

Search active weather alerts (watches, warnings, advisories) across the US. Filter by state, coordinates, zone, land/marine region, event type, severity, urgency, or certainty. area, point, zone, region_type, and region are mutually exclusive — provide at most one. Omit all filters for a national search.

Parameters12

area	string	optional	US state/territory code (e.g., "WA", "OK", "PR") or marine area code (e.g., "GM"). Mutually exclusive with point and zone.
point	string	optional	Coordinates as "lat,lon" (e.g., "47.6,-122.3"). Returns alerts whose geometry contains this point. Mutually exclusive with area and zone.
zone	string	optional	NWS forecast zone (e.g., "WAZ558") or county zone (e.g., "WAC033"). Mutually exclusive with area and point.
region_type	string	optional	Restrict to land-based or marine alerts. Mutually exclusive with area, point, zone, and region.
region	array	optional	Restrict to NWS marine region groups: "AL" (Alaska waters), "AT" (Atlantic Ocean), "GL" (Great Lakes), "GM" (Gulf of Mexico), "PA" (Eastern Pacific and US West Coast), "PI" (Central and Western Pacific). Marine alerts only — a land alert never matches. Mutually exclusive with area, point, zone, and region_type.
event	array	optional	Filter to specific event types (e.g., ["Tornado Warning"]). Matches are case-insensitive and partial, so "tornado" matches both "Tornado Warning" and "Tornado Watch". Use nws_list_alert_types to discover valid names.
severity	array	optional	Filter by severity level.
urgency	array	optional	Filter by urgency level.
certainty	array	optional	Filter by certainty level.
status	string	optional	Alert status filter. Default "Actual". Use a different value only when you specifically need non-live alerts.
limit	integer	optional	Maximum number of alerts to include in this page (1-25, default 25). totalCount still reports the full number of distinct matches, so a small limit returns a digest of broad or national searches without dropping the total; pass the returned nextCursor as cursor to reach the rest.
cursor	string	optional	Opaque continuation token from a previous response's nextCursor. Omit for the first page. The token carries its own page size, so limit applies to the first page only. Every call re-fetches the active-alert feed, so alerts are contiguous within one response but not across calls — the active set changes continuously as alerts are issued and expire, so a continued page covers the collection as it stands at that moment.

Raw schema

{
  "type": "object",
  "properties": {
    "area": {
      "description": "US state/territory code (e.g., \"WA\", \"OK\", \"PR\") or marine area code (e.g., \"GM\"). Mutually exclusive with point and zone.",
      "type": "string"
    },
    "point": {
      "description": "Coordinates as \"lat,lon\" (e.g., \"47.6,-122.3\"). Returns alerts whose geometry contains this point. Mutually exclusive with area and zone.",
      "type": "string"
    },
    "zone": {
      "description": "NWS forecast zone (e.g., \"WAZ558\") or county zone (e.g., \"WAC033\"). Mutually exclusive with area and point.",
      "type": "string"
    },
    "region_type": {
      "description": "Restrict to land-based or marine alerts. Mutually exclusive with area, point, zone, and region.",
      "type": "string",
      "enum": [
        "Land",
        "Marine"
      ]
    },
    "region": {
      "description": "Restrict to NWS marine region groups: \"AL\" (Alaska waters), \"AT\" (Atlantic Ocean), \"GL\" (Great Lakes), \"GM\" (Gulf of Mexico), \"PA\" (Eastern Pacific and US West Coast), \"PI\" (Central and Western Pacific). Marine alerts only — a land alert never matches. Mutually exclusive with area, point, zone, and region_type.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "AL",
          "AT",
          "GL",
          "GM",
          "PA",
          "PI"
        ]
      }
    },
    "event": {
      "description": "Filter to specific event types (e.g., [\"Tornado Warning\"]). Matches are case-insensitive and partial, so \"tornado\" matches both \"Tornado Warning\" and \"Tornado Watch\". Use nws_list_alert_types to discover valid names.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "severity": {
      "description": "Filter by severity level.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Extreme",
          "Severe",
          "Moderate",
          "Minor",
          "Unknown"
        ]
      }
    },
    "urgency": {
      "description": "Filter by urgency level.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Immediate",
          "Expected",
          "Future",
          "Past"
        ]
      }
    },
    "certainty": {
      "description": "Filter by certainty level.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Observed",
          "Likely",
          "Possible",
          "Unlikely",
          "Unknown"
        ]
      }
    },
    "status": {
      "description": "Alert status filter. Default \"Actual\". Use a different value only when you specifically need non-live alerts.",
      "default": "Actual",
      "type": "string",
      "enum": [
        "Actual",
        "Exercise",
        "System",
        "Test",
        "Draft"
      ]
    },
    "limit": {
      "default": 25,
      "description": "Maximum number of alerts to include in this page (1-25, default 25). totalCount still reports the full number of distinct matches, so a small limit returns a digest of broad or national searches without dropping the total; pass the returned nextCursor as cursor to reach the rest.",
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    },
    "cursor": {
      "description": "Opaque continuation token from a previous response's nextCursor. Omit for the first page. The token carries its own page size, so limit applies to the first page only. Every call re-fetches the active-alert feed, so alerts are contiguous within one response but not across calls — the active set changes continuously as alerts are issued and expire, so a continued page covers the collection as it stands at that moment.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

nws_get_alert_counts

Count active weather alerts nationwide, per state/territory or marine area, and per marine region, in one small response — the answer to "how many alerts are active, and where" without fetching the alerts themselves. Counts cover every message status, Test and Exercise included, so totalAlerts can run above the totalCount a national nws_search_alerts search reports under its default status of Actual. An alert counts once in each area its zones fall in, so the area counts can sum past totalAlerts; landAlerts plus marineAlerts equals totalAlerts. Takes no filters. For counts per zone or under a filter, call nws_search_alerts with that zone or filter and read its totalCount.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

nws_get_observations

Get current weather observations (actual measured conditions). Accepts coordinates (resolves nearest station automatically) or a station ID directly (e.g., "KSEA").

Parameters3

latitude	number	optional	Latitude for automatic station resolution. Use with longitude. Ignored if station_id is provided.
longitude	number	optional	Longitude for automatic station resolution. Use with latitude. Ignored if station_id is provided.
station_id	string	optional	Station identifier directly (e.g., "KSEA", "KORD"). Use nws_find_stations to discover station IDs.

Raw schema

{
  "type": "object",
  "properties": {
    "latitude": {
      "description": "Latitude for automatic station resolution. Use with longitude. Ignored if station_id is provided.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "description": "Longitude for automatic station resolution. Use with latitude. Ignored if station_id is provided.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "station_id": {
      "description": "Station identifier directly (e.g., \"KSEA\", \"KORD\"). Use nws_find_stations to discover station IDs.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

nws_get_observation_history

Get a station's recent observation history, newest first — the trend behind the single latest reading nws_get_observations returns (is pressure falling, is the wind picking up). NWS keeps about the last 7 days per station, and a busy airport station reports as often as every 5 minutes, so a day can run past 100 observations: narrow with start (inclusive) and end (exclusive), and page back to older observations with nextCursor. Takes a station ID; use nws_find_stations to find one near a coordinate.

Parameters5

station_id	string	required	Observation station ID (e.g., "KSEA"), case-insensitive. Use nws_find_stations to discover station IDs near a coordinate.
start	string	optional	Earliest observation time to include (inclusive), as an ISO 8601 date-time with seconds and an offset (e.g., "2026-09-30T00:00:00Z" or "2026-09-29T17:00:00-07:00"). Omit to reach back as far as NWS keeps, about 7 days.
end	string	optional	Time to stop before (exclusive), in the same format as start. Omit to start from the most recent observation.
limit	integer	optional	Observations per page (1-100), newest first. When a page fills the limit, pass its nextCursor back as cursor for older observations.
cursor	string	optional	Opaque continuation token from a previous response's nextCursor. Omit for the first page. It carries that query's start, end, and limit, so those inputs apply to the first page only. Each page continues from just before the oldest observation of the one before it, so pages neither repeat nor skip an observation.

Raw schema

{
  "type": "object",
  "properties": {
    "station_id": {
      "type": "string",
      "minLength": 1,
      "description": "Observation station ID (e.g., \"KSEA\"), case-insensitive. Use nws_find_stations to discover station IDs near a coordinate."
    },
    "start": {
      "description": "Earliest observation time to include (inclusive), as an ISO 8601 date-time with seconds and an offset (e.g., \"2026-09-30T00:00:00Z\" or \"2026-09-29T17:00:00-07:00\"). Omit to reach back as far as NWS keeps, about 7 days.",
      "type": "string"
    },
    "end": {
      "description": "Time to stop before (exclusive), in the same format as start. Omit to start from the most recent observation.",
      "type": "string"
    },
    "limit": {
      "default": 24,
      "description": "Observations per page (1-100), newest first. When a page fills the limit, pass its nextCursor back as cursor for older observations.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "description": "Opaque continuation token from a previous response's nextCursor. Omit for the first page. It carries that query's start, end, and limit, so those inputs apply to the first page only. Each page continues from just before the oldest observation of the one before it, so pages neither repeat nor skip an observation.",
      "type": "string"
    }
  },
  "required": [
    "station_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

nws_find_stations

Find weather observation stations near a location. Returns stations sorted by proximity with distance and bearing. Use to discover station IDs for nws_get_observations.

Parameters4

latitude	number	required	Center latitude for proximity search.
longitude	number	required	Center longitude for proximity search.
limit	integer	optional	Max stations per page (1-50). totalCount still reports every station near the point, so pass the returned nextCursor as cursor to reach the rest.
cursor	string	optional	Opaque continuation token from a previous response's nextCursor. Omit for the first page. The token carries its own page size, so limit applies to the first page only. Every call re-fetches the station list, so pages are contiguous within one response; the registry changes rarely, but a later call can window an updated list.

Raw schema

{
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Center latitude for proximity search."
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "Center longitude for proximity search."
    },
    "limit": {
      "default": 10,
      "description": "Max stations per page (1-50). totalCount still reports every station near the point, so pass the returned nextCursor as cursor to reach the rest.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "cursor": {
      "description": "Opaque continuation token from a previous response's nextCursor. Omit for the first page. The token carries its own page size, so limit applies to the first page only. Every call re-fetches the station list, so pages are contiguous within one response; the registry changes rarely, but a later call can window an updated list.",
      "type": "string"
    }
  },
  "required": [
    "latitude",
    "longitude"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

nws_list_alert_types

List all valid NWS alert event type names. Use to discover valid values for the event filter in nws_search_alerts, or to browse alert categories. No parameters required.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

nws_get_office_discussion

Get the latest narrative forecast product from a Weather Forecast Office (WFO). The default product is AFD (Area Forecast Discussion), which explains the meteorological reasoning behind the forecast — synoptic setup, model guidance, and forecaster confidence. Other types: HWO (Hazardous Weather Outlook, 1-7 day severe/flood/winter outlook), ZFP (Zone Forecast Product, zone-by-zone text), SPS (Special Weather Statement, short-fuse advisory). The office code is the 3-letter WFO identifier returned as the "office" field by nws_get_forecast.

Parameters2

office	string	required	Three-letter Weather Forecast Office (WFO) code (e.g., "SEW" for Seattle, "LOX" for Los Angeles). Returned as the "office" field in nws_get_forecast output.
product_type	string	optional	Product type code. AFD (Area Forecast Discussion) — meteorological reasoning, model analysis, forecaster confidence. HWO (Hazardous Weather Outlook) — 1-7 day outlook for severe weather, flooding, winter weather. ZFP (Zone Forecast Product) — detailed zone-by-zone text forecast. SPS (Special Weather Statement) — short-fuse advisory for notable non-warning weather.

Raw schema

{
  "type": "object",
  "properties": {
    "office": {
      "type": "string",
      "minLength": 1,
      "description": "Three-letter Weather Forecast Office (WFO) code (e.g., \"SEW\" for Seattle, \"LOX\" for Los Angeles). Returned as the \"office\" field in nws_get_forecast output."
    },
    "product_type": {
      "description": "Product type code. AFD (Area Forecast Discussion) — meteorological reasoning, model analysis, forecaster confidence. HWO (Hazardous Weather Outlook) — 1-7 day outlook for severe weather, flooding, winter weather. ZFP (Zone Forecast Product) — detailed zone-by-zone text forecast. SPS (Special Weather Statement) — short-fuse advisory for notable non-warning weather.",
      "default": "AFD",
      "type": "string",
      "enum": [
        "AFD",
        "HWO",
        "ZFP",
        "SPS"
      ]
    }
  },
  "required": [
    "office"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

nws_get_zone_forecast

Get the text forecast for a public NWS forecast zone. Returns named forecast periods (e.g., "Today", "Tonight", "Monday") with detailed narrative text — the human-readable, zone-level forecast written by local forecasters. Completes the alert-to-forecast chain: nws_search_alerts returns each affected zone in "affectedZones" as a code plus a type, and nws_find_stations returns codes in the "forecastZone" column. Only affectedZones entries with type "forecast" work here; entries typed "county" or "fire" have no text forecast upstream and will not resolve, and neither do marine forecast zones (e.g., "PZZ251", "GMZ056"). Zone codes follow the pattern XXZ### (e.g., "WAZ315" for Western Washington lowlands).

Parameters1

zone_id

string

required

NWS public forecast zone code (e.g., "WAZ315" for the Western Washington lowlands including Seattle). Returned as "forecastZone" by nws_get_forecast and nws_find_stations, or as the "code" of an "affectedZones" entry with type "forecast" in nws_search_alerts. Format: two-letter state + "Z" + three-digit number.

Raw schema

{
  "type": "object",
  "properties": {
    "zone_id": {
      "type": "string",
      "minLength": 1,
      "description": "NWS public forecast zone code (e.g., \"WAZ315\" for the Western Washington lowlands including Seattle). Returned as \"forecastZone\" by nws_get_forecast and nws_find_stations, or as the \"code\" of an \"affectedZones\" entry with type \"forecast\" in nws_search_alerts. Format: two-letter state + \"Z\" + three-digit number."
    }
  },
  "required": [
    "zone_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md14 KBView on GitHub

@cyanheads/nws-weather-mcp-server

Get US weather forecasts, active alerts, and current observations via the National Weather Service API. STDIO or Streamable HTTP.

9 Tools • 1 Resource

Version MCP SDK TypeScript Bun

Public Hosted Server: https://nws.caseyjhand.com/mcp

Overview

US weather data from the National Weather Service API (api.weather.gov). Get forecasts, active alerts, current observations, forecast-office narrative products, and zone-level text forecasts for any coordinate in the 50 states and US territories, plus national alert counts and a station's last ~7 days of observations. Adjacent marine areas are covered by alerts, plus stations and observations near the coast; NWS publishes no point or zone text forecast for them. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`nws_get_forecast`	7-day or hourly forecast for coordinates. Resolves NWS grid internally.
`nws_search_alerts`	Active weather alerts filtered by area, point, zone, event, severity, urgency, certainty, and status.
`nws_get_alert_counts`	Active alert counts nationwide, per state/territory or marine area, and per marine region.
`nws_get_observations`	Current conditions by coordinates (nearest station) or station ID.
`nws_get_observation_history`	A station's recent observations, newest first, paged back through the ~7 days NWS keeps.
`nws_find_stations`	Nearby observation stations sorted by distance with bearing.
`nws_list_alert_types`	All valid alert event type names for filter discovery.
`nws_get_office_discussion`	Latest narrative product (AFD, HWO, ZFP, SPS) from a Weather Forecast Office.
`nws_get_zone_forecast`	Text forecast periods for a public NWS forecast zone.

Resources

Resource	Description
`nws://alert-types`	Static list of all valid NWS alert event type names.

Also reachable via the nws_list_alert_types tool, for MCP clients that don't support resources.

Capability reference

`nws_get_forecast` _tool

latitude + longitude; returns named 12-hour periods by default (14, ~7 days), or with hourly: true one-hour periods with dewpoint and humidity, 48 per page of the ~156 upstream
Returns the forecastZone and county zone codes for chaining into nws_search_alerts; marine coordinates fail with a typed marine_forecast_unsupported error pointing to a nearby land point or nws_search_alerts, and land points NWS serves no forecast grid for with no_forecast_grid

`nws_search_alerts` _tool

At most one location filter — area, point, zone, region_type, or region — or none for a national search; event matches case-insensitively and partially; status defaults to Actual (also Exercise, System, Test, Draft); limit 1-25 (default 25) per page
Each affectedZones entry carries its zone type (forecast/county/fire), marking which codes chain into nws_get_zone_forecast; CAP message-lifecycle fields (sent, effective, status, messageType, references) are distinct from the hazard's own onset/ends

`nws_get_alert_counts` _tool

No input; returns national totalAlerts (landAlerts + marineAlerts), plus areas counts keyed by state/territory or marine area code and regions counts keyed by marine region (AL, AT, GL, GM, PA, PI), each listing only codes with an active alert
Counts cover every message status, Test and Exercise included, so totalAlerts can exceed a national nws_search_alerts totalCount (status: Actual by default); an alert counts once in each area its zones fall in, so areas can sum past totalAlerts

`nws_get_observations` _tool

Look up by coordinates (resolves nearest station) or station_id directly
Dual-unit display on every measurement (F/C, mph/km/h, inHg/hPa, mi/km); observations older than 2 hours carry a staleness notice, and a separate warning flags a station with most measurements unavailable

`nws_get_observation_history` _tool

station_id (from nws_find_stations); optional start (inclusive) and end (exclusive) as ISO 8601 date-times with seconds and an offset; limit 1-100 (default 24) per page, newest first, back through the ~7 days NWS keeps
Each observation carries the nws_get_observations measurement fields, null where the station reported nothing; an unknown station fails with station_not_found, and a malformed window or a start not before end with invalid_time_window
nextCursor appears only when a page fills limit, and pages neither repeat nor skip an observation; no totalCount, since NWS reports none for a window

`nws_find_stations` _tool

latitude + longitude; optional limit (1-50, default 10) sizes the page
Nearest first; each result carries the station ID for nws_get_observations, distance (km), bearing, zone codes, elevation, and time zone

`nws_list_alert_types` _tool

Returns the full set of event types the NWS API recognizes (e.g., "Tornado Warning", "Heat Advisory")
Use to discover valid values for the event filter in nws_search_alerts

`nws_get_office_discussion` _tool

office: 3-letter WFO code (e.g., "SEW" for Seattle), returned as the office field by nws_get_forecast; product_type: AFD (default), HWO, ZFP, or SPS
Returns productText plus issuanceTime, issuingOffice, productName, productCode, wmoCollectiveId; an unknown office, or a valid office with no current product of the requested type, fails with a typed no_products error

`nws_get_zone_forecast` _tool

zone_id: forecast zone code (e.g., "WAZ315") — returned by nws_get_forecast (forecastZone), nws_find_stations (forecastZone column), and nws_search_alerts (the code of an affectedZones entry with type: "forecast")
Returns named periods (e.g., "Today", "Tonight", "Monday") with narrative text from local forecasters; county (XXC###), fire, and unknown zone codes fail with a typed zone_not_found error, marine forecast zones (e.g., PZZ251) with marine_forecast_unsupported, and a valid zone NWS publishes no text forecast for with zone_forecast_unavailable, which carries a point inside the zone for nws_get_forecast

`nws://alert-types` _resource

Static list of all valid NWS alert event type names, returned as application/json
No parameters; cached publicly for 1 hour

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.

NWS-specific:

Sends the required User-Agent header automatically (configurable via NWS_USER_AGENT) — NWS returns 403 without one
Automatic coordinate-to-grid resolution via /points, cached for 1h since grid cells rarely change
Request timeouts plus retry/backoff for transient NWS API failures
Zero-auth access — no API keys required
Paged results — nws_get_forecast, nws_find_stations, and nws_search_alerts report totalCount against this page's shown, and nws_get_observation_history reports shown alone (NWS gives no total for a time window); pass the returned nextCursor back as cursor for the next page (omitted on the last page)

Agent-friendly output:

Provenance — forecast, observation, and station responses echo office codes, time zones, and forecast/county zone codes so agents can chain directly into nws_get_office_discussion, nws_get_zone_forecast, and nws_search_alerts without re-deriving them
Guidance over silence — empty, truncated, or cursor-past-end results carry a notice naming the cause and the concrete next step, rather than an empty array or a bare page
Discriminated output contracts — zone type (forecast/county/fire), CAP status/messageType distinct from hazard onset/ends, and typed error reasons (invalid_area_code, no_products, zone_not_found, …) — callers branch on data, not string parsing
Response shaping — upstream single-unit floats are normalized into dual-unit pairs (F/C, mph/km/h, inHg/hPa, mi/km) and rounded to match what format() renders, so structured and text output agree

Getting started

Public Hosted Instance

A public instance is available at https://nws.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

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

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

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

Or with npx (no Bun required):

json

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

Or with Docker:

json

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

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_SESSION_MODE=stateless MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Node.js v24+ or Bun v1.4+

Installation

Clone the repository:

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

Navigate into the directory:

cd nws-weather-mcp-server

Install dependencies:

bun install

Configuration

Variable	Description	Default
`NWS_USER_AGENT`	User-Agent for NWS API requests. The API requires this header.	`(nws-weather-mcp-server, ...)`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for HTTP server.	`3010`
`MCP_HTTP_HOST`	Hostname for HTTP server.	`127.0.0.1`
`MCP_SESSION_MODE`	HTTP session mode: `stateful`, `stateless`, or `auto`.	`stateless`
`MCP_LOG_LEVEL`	Log level: `debug`, `info`, `notice`, `warning`, `error`.	`info`

See .env.example for the full list including auth, storage, and OpenTelemetry options.

Running the server

Local development

Build and run the production version:

# One-time build
bun run rebuild

# Run the built server
bun run start:http
# or
bun run start:stdio

Run checks and tests:

bun run devcheck     # Lints, formats, type-checks
bun run test         # Runs test suite

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools and the resource.
`src/mcp-server/tools/definitions/`	Tool definitions (`*.tool.ts`).
`src/mcp-server/resources/definitions/`	Resource definitions (`*.resource.ts`).
`src/services/nws/`	NWS API client and response types.
`src/config/`	Environment variable parsing and validation with Zod.
`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 domain-specific logging, ctx.state for storage
Add new tools/resources to the barrel exports and the createApp() arrays in src/index.ts
Wrap NWS API calls: validate raw JSON → normalize to domain types → return the output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (9)

nws_get_forecastnws_search_alertsnws_get_alert_countsnws_get_observationsnws_get_observation_historynws_find_stationsnws_list_alert_typesnws_get_office_discussion

Configuration

Environment variables

NWS_USER_AGENTdefault (nws-weather-mcp-server, github.com/cyanheads/nws-weather-mcp-server)

User-Agent header for NWS API requests. The API requires this header but a default is provided.

MCP_LOG_LEVELdefault info

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

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": {
    "nws-weather-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/nws-weather-mcp-server@0.10.0",
        "run",
        "start:stdio"
      ],
      "env": {
        "NWS_USER_AGENT": "(nws-weather-mcp-server, github.com/cyanheads/nws-weather-mcp-server)",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

@cyanheads/nws-weather-mcp-server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

nws_get_forecast

nws_search_alerts

nws_get_alert_counts

nws_get_observations

nws_get_observation_history

nws_find_stations

nws_list_alert_types

nws_get_office_discussion

nws_get_zone_forecast

@cyanheads/nws-weather-mcp-server

Overview

Tools

Resources

Capability reference

nws_get_forecast tool

nws_search_alerts tool

nws_get_alert_counts tool

nws_get_observations tool

nws_get_observation_history tool

nws_find_stations tool

nws_list_alert_types tool

nws_get_office_discussion tool

nws_get_zone_forecast tool

nws://alert-types resource

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`nws_get_forecast` _tool

`nws_search_alerts` _tool

`nws_get_alert_counts` _tool

`nws_get_observations` _tool

`nws_get_observation_history` _tool

`nws_find_stations` _tool

`nws_list_alert_types` _tool

`nws_get_office_discussion` _tool

`nws_get_zone_forecast` _tool

`nws://alert-types` _resource