@cyanheads/nws-weather-mcp-server
by cyanheads
README.md
<div align="center">
<h1>@cyanheads/nws-weather-mcp-server</h1>
<p><b>Get US weather forecasts, active and recent 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">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/nws-weather-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/nws-weather-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](https://github.com/cyanheads/nws-weather-mcp-server/releases/latest/download/nws-weather-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=nws-weather-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvbndzLXdlYXRoZXItbWNwLXNlcnZlciJdfQ==) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22nws-weather-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fnws-weather-mcp-server%22%5D%7D)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
</div>
<div align="center">
**Public Hosted Server:** [https://nws.caseyjhand.com/mcp](https://nws.caseyjhand.com/mcp)
</div>
---
## 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.
## Capability reference
### `nws_get_forecast` <sub>tool</sub>
- `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` <sub>tool</sub>
- 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` <sub>tool</sub>
- `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` <sub>tool</sub>
- 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` <sub>tool</sub>
- 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` <sub>tool</sub>
- `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` <sub>tool</sub>
- `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` <sub>tool</sub>
- 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` <sub>tool</sub>
- `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` <sub>tool</sub>
- `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` <sub>resource</sub>
- 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`](https://github.com/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:
```sh
claude mcp add --transport http nws-weather-mcp-server https://nws.caseyjhand.com/mcp
```
Or run it locally:
```sh
claude mcp add nws-weather-mcp-server -- npx -y @cyanheads/nws-weather-mcp-server
```
For other clients, add this to the MCP config file:
```json
{
"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](#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`](.env.example) for the full list including auth, storage, and OpenTelemetry options.
## Running the server
### Local development
Source development requires [Bun v1.4.4+](https://bun.sh/). The published executable also runs on [Node.js v24+](https://nodejs.org/).
```sh
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:**
```sh
# One-time build
bun run rebuild
# Run the built server
bun run start:http
# or
bun run start:stdio
```
- **Run checks and tests:**
```sh
bun run devcheck # Lints, formats, type-checks
bun run test # Runs test suite
```
### Docker
```sh
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`](./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:
```sh
bun run devcheck
bun run test
```
## License
Apache-2.0 — see [LICENSE](LICENSE) for details.
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessNo recent community issues