io.github.cyanheadsPublished by GitHub account cyanheadsv0.12.0Updated Oct 29, 2026
Get US weather forecasts, active alerts, and current observations.
Serves real-time US National Weather Service data: forecasts, active alerts, station observations, and forecaster discussions for any US point.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.cyanheads%2Fnws-weather-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"nws-weather": {
"type": "http",
"url": "https://nws.caseyjhand.com/mcp"
}
}
}Get US weather forecasts, active alerts, and current observations via the National Weather Service API. STDIO or Streamable HTTP.
Public Hosted Server: https://nws.caseyjhand.com/mcp
Real-time US weather from the National Weather Service: forecasts, active alerts, current conditions, and forecaster discussions for any point in the 50 states and US territories, plus zone forecasts, coastal and marine alerts, and a week of station history. No API key required.
Alert types are also reachable via nws_list_alert_types. The weather guide is available through the MCP Skills extension and in the plugin's skills/ directory.
nws_get_forecast toollatitude + longitude; returns 14 named 12-hour periods (~7 days) by default, or with hourly: true one-hour periods with dewpoint and humidity, 48 per page of the ~156 upstreamnextCursor carries its mode, so an hourly walk continues hourly without resending hourly: trueinclude_amounts: true adds every native quantitativePrecipitation, snowfallAmount, and iceAccumulation interval as precipitationAmounts (layer, uom, values with validTime and value), plus the separate amountsUpdateTime. Default false; resend it on any cursor page that needs amounts. Interval strings, units, zeroes, and nulls stay unchanged. Missing layers and unavailable amounts are explained in notice; present empty layers carry values: []. Absent units or update time are null. An unavailable amount feed leaves the main forecast available.updateTime, when the grid's forecast data was last updated, beside generatedAt; a notice flags a grid not updated in more than 24 hoursforecastZone and county zone codes for chaining into nws_search_alertsmarine_forecast_unsupported, and land points NWS serves no forecast grid for fail with no_forecast_gridnws_search_alerts toolarea, 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 (default 25) is capped at 25; a larger limit is served as 25 and reported through requestedLimit/effectiveLimitnextCursor carries the query's filters and page size, so pass it back as cursor on its own; filters sent with it are ignoredaffectedZones entry carries its zone type (forecast/county/fire); references lists superseded messages newest first by sent; a point outside NWS coverage fails with invalid_pointoffice (the issuing office code for nws_get_office_discussion, e.g. RIW), raw vtec strings, the nwsHeadline, and hazard tags such as maxHailSize and maxWindGust, verbatimnws_get_alert toolalert_id: an alert id from nws_search_alerts, or a references[].identifier from any alert; returns { alert } in the same shape as nws_search_alerts, including superseded messagesalert_not_foundnws_get_alert_counts tooltotalAlerts (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 alerttotalAlerts 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 totalAlertsnws_get_observations toolstation_id directly0 a trace and null no amount reported; observations older than 2 hours carry a staleness notice, and a separate warning flags a station with most measurements unavailablenws_get_observation_history toolstation_id (from nws_find_stations); optional start (inclusive) and end (exclusive) as ISO 8601 date-times with seconds and an offset; newest first, back through the ~7 days NWS keepslimit (default 24) is capped at 100; a larger limit is served as 100 and reported through requestedLimit/effectiveLimitnws_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_windownextCursor appears only when older observations remain; there is no totalCount, since NWS reports none for a windownws_find_stations toollatitude + longitude; optional limit (default 10) is capped at 50; a larger limit is served as 50 and reported through requestedLimit/effectiveLimitnws_get_observations, distance (km), bearing, zone codes, elevation, and time zonenws_list_alert_types toolevent filter in nws_search_alertsnws_get_office_discussion tooloffice: usually the 3-letter WFO code (e.g., "SEW" for Seattle) returned as the office field by nws_get_forecast; product_type: AFD (default), HWO, ZFP, SPS, or FWF (Fire Weather Planning Forecast)productText plus issuanceTime, issuingOffice, productName, productCode, wmoCollectiveId; content[] carries the product text in a text code block, so fixed-width tables keep their columns; an unknown office, or one with no current product of the requested type, fails with no_productsoutline of its sections instead of productText; pass sections (AFD section names, or zone codes for ZFP/HWO/SPS/FWF) to get the matching sections, and an unknown name fails with unknown_sectionfire gets its forecast from the FWF: office from the alert's office field, product_type: "FWF", sections: [<zone code>]nws_get_zone_forecast toolzone_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")XXC###) and unknown zone codes fail with zone_not_found, and so do most fire zone codes, whose forecast is their segment of the office FWF on nws_get_office_discussion; a fire code that is also a public zone code returns the public zone's forecast; marine zones with no text forecast fail with marine_forecast_unsupported, and land zones with none with zone_forecast_unavailablenws://alert-types resourceapplication/jsonBuilt 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:
User-Agent header automatically (configurable via NWS_USER_AGENT) — NWS returns 403 without one/points, cached for 1h since grid cells rarely changenextCursor back as cursor for the next page (omitted on the last page)Agent-friendly output:
nws_get_office_discussion, nws_get_zone_forecast, and nws_search_alertsnotice naming the cause and the next stepinvalid_area_code, no_products, zone_not_found, …) so callers branch on data, not string parsingConnect to the hosted instance, no install:
Or run it locally:
For other clients, add this to the MCP config file:
NWS_USER_AGENT optionally sets the contact identifier sent to NWS. For Docker or a source build, see Running the server.
See .env.example for the full list including auth, storage, and OpenTelemetry options.
Source development requires Bun v1.4+. The published executable also runs on Node.js v24+.
Build and run the production version:
Run checks and tests:
The image defaults to HTTP transport, stateless session mode, and logs to /var/log/nws-weather-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/nws-weather-mcp-server:latest"]. To build locally, docker build -t nws-weather-mcp-server .; OpenTelemetry peers are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
See CLAUDE.md for development guidelines and architectural rules. The short version:
try/catch in tool logicctx.log for domain-specific logging, ctx.state for storagecreateApp() arrays in src/index.tsIssues are welcome. Run checks before submitting:
Apache-2.0 — see LICENSE for details.
Source: README.md at commit 7229c3c
Nws Get Forecast
Get the weather forecast for a US location. Returns either named 12-hour periods (default) or hourly breakdowns.
cursorhourlylatituderequiredlongituderequiredinclude_amountsNws 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.
areazoneeventlimitpointcursorregionstatusurgencyseveritycertaintyregion_typeNws Get Alert
Fetch one NWS alert message by ID — a current alert, or an earlier message that an update or cancellation has since superseded and that an active-alert search no longer returns. Takes an id from nws_search_alerts or a references[].identifier from any alert, and returns the same alert fields nws_search_alerts does. The message carries its own references, newest first, so a revision chain is walked one call per message. Every reference sharing the newest sent time is an immediate predecessor (an update can merge several earlier segments), so references[0] is one of them, not always the only one. NWS serves messages for about 7 days after they are sent.
alert_idrequiredNws 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.
Takes no parameters.
Nws Get Observations
Get current weather observations (actual measured conditions). Accepts coordinates (resolves nearest station automatically) or a station ID directly (e.g., "KSEA").
latitudelongitudestation_idNws 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.
endlimitstartcursorstation_idrequiredNws 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.
limitcursorlatituderequiredlongituderequiredNws 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.
Takes no parameters.
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), FWF (Fire Weather Planning Forecast, one segment per fire weather zone). The office code is the 3-letter WFO identifier returned as the "office" field by nws_get_forecast. A product over 24,000 bytes (most ZFPs and FWFs) comes back as an outline of its sections — AFD section names, or ZFP/HWO/SPS/FWF zone segments with their area names — with each section's size, instead of the text; re-call with sections to get the ones you need. sections also works on a product of any size, to read one AFD section or one zone's forecast. For an alert zone typed "fire" (Red Flag Warning, Fire Weather Watch), pass the alert's "office" field as office, product_type "FWF", and the zone code in sections.
officerequiredsectionsproduct_typeNws Get Zone Forecast
Get the text forecast for an 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" have no text forecast upstream and will not resolve. An entry typed "fire" has its forecast in a segment of the office's Fire Weather Planning Forecast: call nws_get_office_discussion with office set to the alert's "office" field, product_type "FWF", and sections set to the zone code; a fire zone code that is also a public zone code (e.g., "NDZ040") returns that public zone's forecast here, not the fire weather forecast. Marine forecast zones vary: many coastal zones serve a text forecast of wind and seas (e.g., "PZZ251"), while offshore zones (e.g., "GMZ056") and some coastal ones have none. Zone codes follow the pattern XXZ### (e.g., "WAZ315" for the City of Seattle).
zone_idrequired100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
claude mcp add --transport http nws-weather-mcp-server https://nws.caseyjhand.com/mcpclaude mcp add nws-weather-mcp-server -- npx -y @cyanheads/nws-weather-mcp-server{ "mcpServers": { "nws-weather-mcp-server": { "command": "npx", "args": ["-y", "@cyanheads/nws-weather-mcp-server"] } }}git clone https://github.com/cyanheads/nws-weather-mcp-server.gitcd nws-weather-mcp-server && bun installcp .env.example .env# One-time buildbun run rebuild
# Run the built serverbun run start:http# orbun run start:stdiobun run devcheck # Lints, formats, type-checksbun run test # Runs test suitedocker run --rm -p 3010:3010 ghcr.io/cyanheads/nws-weather-mcp-server:latestbun run devcheckbun run test