Skip to main content
Glama
@cyanheads/nws-weather-mcp-server

@cyanheads/nws-weather-mcp-server

by cyanheads

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework

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


Overview

Real-time US weather from the National Weather Service: forecasts, active and recent 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.

Tools

Tool

Description

nws_get_forecast

7-day or hourly forecast for coordinates. Resolves NWS grid internally.

nws_search_alerts

Active weather alerts, or the alert messages issued in a window within the last 7 days, filtered by area, point, zone, event, severity, urgency, certainty, message type, and status.

nws_get_alert

One alert message by ID, current or superseded (~7-day retention).

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, FWF) from a Weather Forecast Office; a product too large to inline comes back as a section outline.

nws_get_zone_forecast

Text forecast periods for an NWS forecast zone.

Resources

Resource

Description

nws://alert-types

Static list of all valid NWS alert event type names.

skill://nws-weather-guide/SKILL.md

Decision gates for combining forecasts, alerts, station trends, and forecaster discussions.

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.

Related MCP server: weather

Capability reference

nws_get_forecast tool

  • latitude + 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 upstream

  • nextCursor carries its mode, so an hourly walk continues hourly without resending hourly: true

  • include_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.

  • Returns updateTime, when the grid's forecast data was last updated, beside generatedAt; a notice flags a grid not updated in more than 24 hours

  • Returns the forecastZone and county zone codes for chaining into nws_search_alerts

  • Marine coordinates fail with marine_forecast_unsupported, whose recovery sends a coastal zone starting AMZ, ANZ, GMZ, PHZ, or PZZ to nws_get_zone_forecast for its text forecast of wind and seas (Great Lakes, most Alaska, Guam, American Samoa, and offshore zones have none), and land points NWS serves no forecast grid for fail 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); message_type (Alert, Update, Cancel) filters active and windowed searches alike

  • start and/or end (ISO 8601 date-times with seconds and an offset, read as in nws_get_observation_history; either alone, or equal to each other) switch to window mode: every alert message issued in the window, updates and cancellations included, newest first, for questions like whether a place was under a warning at a past time. Both ends are inclusive and bound when a message was sent, not when its hazard was in effect, so a warning issued before start is missed even while still in effect. NWS keeps messages for 7 days; a window reaching past that says so in notice. Malformed or calendar-invalid values, or start after end, fail with invalid_time_window

  • A windowed search reports shown without totalCount, since NWS gives no total; event still matches partially, and a term matching no event type returns no alerts with a notice

  • limit (default 25) is capped at 25; a larger limit is served as 25 and reported through requestedLimit/effectiveLimit

  • nextCursor carries the query's filters, window, and page size, so pass it back as cursor on its own; filters sent with it are ignored. A windowed walk returns each message once, however many share an issuance time

  • Each affectedZones entry carries its zone type (forecast/county/fire); references lists superseded messages newest first by sent; a point outside NWS coverage fails with invalid_point

  • Each alert carries office (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, verbatim


nws_get_alert tool

  • alert_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 messages

  • A malformed ID, an unknown one, and one past NWS's ~7-day retention all fail with alert_not_found


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

  • barometricPressurePa is the altimeter setting (METAR A group; other networks such as CWOP fill it with their own reading); seaLevelPressurePa is the sea-level pressure from an hourly METAR's SLP remark, null on 5-minute records and whenever NWS sends none. They differ by several hPa at high-elevation stations, and each renders on its own line (Altimeter, Sea-Level Pressure)

  • Dual-unit display on every measurement (F/C, mph/km/h, inHg/hPa, mi/km, in/mm), temperatures to one decimal; 1-, 3-, and 6-hour precipitation amounts from hourly reports, with 0 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 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 (lowercase t/z and an offset without its colon, +0000, also read); newest first, back through the ~7 days NWS keeps

  • limit (default 24) is capped at 100; a larger limit is served as 100 and reported through requestedLimit/effectiveLimit

  • Each observation carries the nws_get_observations measurement fields, altimeter (barometricPressurePa) and sea-level pressure (seaLevelPressurePa, hourly records only) included and rendered as separate table columns, 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 older observations remain; there is no totalCount, since NWS reports none for a window


nws_find_stations tool

  • latitude + longitude; optional limit (default 10) is capped at 50; a larger limit is served as 50 and reported through requestedLimit/effectiveLimit

  • 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: 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)

  • Returns 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_products

  • A product too large to inline (most ZFPs and FWFs) returns an outline 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_section

  • The newest product on file can be past its expiry: when every zone segment the response carries has passed the expiry in its UGC line (only the selected segments with sections), a notice names that time and says the product is no longer in effect. An SPS usually is, and its notice points to nws_search_alerts with event "Special Weather Statement" for statements in effect now; AFD carries no expiry

  • An alert zone typed fire gets its forecast from the FWF: office from the alert's office field, product_type: "FWF", sections: [<zone code>]


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, and updated, the issuance time of the product it comes from; when NWS sends it 12 hours off (it reads a midnight-hour 12xx AM header as noon; a noon-hour header it reads correctly), the value is corrected and notice names NWS's value, and a time later than the response that cannot be corrected is returned as sent with a notice

  • County (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 (coastal zones starting AMZ, ANZ, GMZ, PHZ, or PZZ usually have one; Great Lakes, most Alaska, Guam, American Samoa, and offshore zones have none), and land zones with none with zone_forecast_unavailable


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 — pass the returned nextCursor back as cursor for the next page (omitted on the last page)

Agent-friendly output:

  • Provenance — responses echo office codes, time zones, and zone codes so agents can chain into nws_get_office_discussion, nws_get_zone_forecast, and nws_search_alerts

  • Guidance over silence — empty, truncated, or cursor-past-end results carry a notice naming the cause and the next step

  • Typed error reasons (invalid_area_code, no_products, zone_not_found, …) so callers branch on data, not string parsing

  • Dual-unit measurements (F/C, mph/km/h, inHg/hPa, mi/km, in/mm), rounded to match the text output

Getting started

Connect to the hosted instance, no install:

claude mcp add --transport http nws-weather-mcp-server https://nws.caseyjhand.com/mcp

Or run it locally:

claude mcp add nws-weather-mcp-server -- npx -y @cyanheads/nws-weather-mcp-server

For other clients, add this to the MCP config file:

{
  "mcpServers": {
    "nws-weather-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/nws-weather-mcp-server"]
    }
  }
}

NWS_USER_AGENT optionally sets the contact identifier sent to NWS. For Docker or a source build, see Running the server.

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

Source development requires Bun v1.4.4+. The published executable also runs on Node.js v24+.

git clone https://github.com/cyanheads/nws-weather-mcp-server.git
cd nws-weather-mcp-server && bun install
cp .env.example .env
  • 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

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/nws-weather-mcp-server:latest

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.

Project structure

Directory

Purpose

src/index.ts

createApp() entry point — registers tools, the alert-types resource, and published skills.

skills/

Published agent skills, also served over MCP.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers