.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/nws-weather-mcp-server</h1> <p><b>Get US weather forecasts, active alerts, and current observations via the National Weather Service API. STDIO or Streamable HTTP.</b> <div>10 Tools • 2 Resources</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

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

</div>

Overview

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.

Tools

Resources

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.

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, 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)
• 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 and page size, so pass it back as cursor on its own; filters sent with it are ignored
• 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
• 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; 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, 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
• 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
• 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, 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

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

Running the server

Local development

Source development requires Bun v1.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

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.