@cyanheads/nws-weather-mcp-server

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

Tools

Seven tools for real-time US weather data:

nws_get_forecast

Get the weather forecast for a US location.

• Default returns named 12-hour periods (14 total, ~7 days)

• Hourly mode returns 48 one-hour periods per page with dewpoint and humidity — the upstream feed carries ~156, and the pre-page total plus a truncation notice are surfaced in the enrichment block

• Pass the returned nextCursor back as cursor to reach the remaining periods; it is omitted on the last page

• Coordinates resolve to NWS grid internally via /points endpoint

• Formatted timestamps use the resolved local time zone

• Returns forecast zone and county zone codes for chaining into nws_search_alerts

nws_search_alerts

Search active weather alerts with flexible filtering.

• Filter by area (state/territory/marine codes), point (lat,lon), zone, land/marine region_type, marine region groups, event type, severity, urgency, certainty, or status

• area, point, zone, region_type, and region are mutually exclusive; specify at most one location filter

• National search when no filters provided

• A filter provided with no usable value — a blank area/point/zone, or an empty event/severity/urgency/certainty/region array — is rejected rather than dropped, so a search never silently widens to national results

• Each affectedZones entry carries its NWS zone type (forecast, county, or fire) alongside the code, so callers can tell which codes chain into nws_get_zone_forecast

• Alerts include the CAP message lifecycle — sent, effective, status, messageType, and the prior messages an update references — distinct from the hazard's own onset/ends

• Event matching is case-insensitive and partial, so "tornado" matches both watches and warnings

• status defaults to live Actual alerts, but can be set to Exercise, System, Test, or Draft

• Optional limit (1–25, default 25) sizes the page; totalCount reports the full match count, with a truncation notice and guidance to narrow filters

• Pass the returned nextCursor back as cursor to reach matches beyond the page. Consecutive pages are contiguous within one response only — every call re-fetches /alerts/active, and that set changes continuously as alerts are issued and expire

• Validates area, point, and zone locally before the API call — malformed values fail fast as invalid_area_code, invalid_point, or invalid_zone instead of leaking a raw upstream 400

nws_get_observations

Current measured conditions from a weather station.

• Look up by coordinates (finds nearest station) or station ID directly

• A blank or whitespace-only station_id is rejected rather than dropped, so coordinates never silently answer for a station that was asked for by name

• Coordinate lookups choose the nearest station from the candidates returned by NWS

• Dual-unit display: F/C, mph/km/h, inHg/hPa, mi/km

• Observation timestamps use the station's local time zone when available

• Warns when most measurements are unavailable from a station

nws_find_stations

Discover nearby observation stations.

• Sorted by haversine distance from query point

• Returns distance (km) and compass bearing

• Includes zone codes, elevation, time zone

• Optional limit (1–50, default 10) sizes the page; totalFound reports every station near the point and holds steady across pages

• Pass the returned nextCursor back as cursor to reach stations beyond the page; it is omitted on the last page

• Useful for finding station IDs for nws_get_observations

nws_list_alert_types

List all valid NWS alert event type names.

• 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

Get the latest narrative product from a Weather Forecast Office (WFO).

• office: 3-letter WFO code (e.g., SEW for Seattle) — returned as the office field by nws_get_forecast

• product_type: AFD (Area Forecast Discussion, default), HWO (Hazardous Weather Outlook), ZFP (Zone Forecast Product), SPS (Special Weather Statement)

• Two-hop fetch: lists products by office/type (newest first), then retrieves full product text

• Returns productText plus issuanceTime, issuingOffice, productName, productCode, wmoCollectiveId

• Unknown office returns a clear error with recovery instructions (the NWS API returns HTTP 200 with an empty list, not a 404)

nws_get_zone_forecast

Get the text forecast for a public NWS forecast zone.

• 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

• Completes the alert-to-forecast chain: look up alert zones, then retrieve zone forecasts

• County (XXC###) and fire zone codes are not supported here — NWS publishes no text forecast for them. They remain valid values for the zone filter on nws_search_alerts

Related MCP server: weather-mcp

Resources

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation

• Unified error handling across all tools

• Pluggable auth (none, jwt, oauth)

• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Structured logging with optional OpenTelemetry tracing

• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

NWS-specific:

• Zero-auth access to the NWS API — no API keys required

• Automatic coordinate-to-grid resolution with caching (1h TTL)

• Request timeouts plus retry/backoff for transient NWS API failures

• Dual-unit display for observations (F/C, mph/km/h, inHg/hPa, mi/km)

• Continental US, Alaska, Hawaii, and US territories coverage

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:

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

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

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

{
  "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_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Node.js v24+ or Bun v1.3+

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd nws-weather-mcp-server

3. Install dependencies:

bun install

Configuration

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

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

Contributing

Issues and pull requests are welcome. Run checks before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.