io.github.cyanheads/nws-weather-mcp-server
Get US weather forecasts, active alerts, and current observations.
Open source Repository Open in the app JSON README (API)
About
Get US weather forecasts, active alerts, and current observations.
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- cyanheads
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.9.2
- Stars
- 1
- Last push
- 2026-09-04T16:53:02Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:39
- Updated
- 2026-09-04 18:00:35
- Origin id
io.github.cyanheads/nws-weather-mcp-server
README
<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>7 Tools • 1 Resource</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/nws-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>
---
## Tools
Seven tools for real-time US weather data:
| Tool | Description |
|:----------|:------------|
| `nws_get_forecast` | 7-day or hourly forecast for coordinates. Resolves NWS grid internally. |
| `nws_search_alerts` | Active weather alerts filtered by area, point, zone, event, severity, urgency, certainty, and status. |
| `nws_get_observations` | Current conditions by coordinates (nearest station) or station ID. |
| `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) from a Weather Forecast Office. |
| `nws_get_zone_forecast` | Text forecast periods for a public NWS forecast zone. |
### `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 (`totalCount`, against this page's `shown`) 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 and `shown` the size of this page, with a truncation notice and guidance to narrow filters
- Alerts NWS repeats verbatim within one fetch are collapsed on `id`, so `totalCount` counts distinct alerts and a duplicate never straddles a page boundary
- 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; `totalCount` reports every station near the point and holds steady across pages, while `shown` is the size of this page
- 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`
## Resources
| URI Pattern | Description |
|:------------|:------------|
| `nws://alert-types` | Static list of all valid NWS alert event type names. |
## Features
Built on [`@cyanheads/mcp-ts-core`](https://github.com/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:
```json
{
"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.
```json
{
"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):
```json
{
"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:
```json
{
"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:
```sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp
```
### Prerequisites
- [Node.js v24+](https://nodejs.org/) or [Bun v1.3+](https://bun.sh/)
### Installation
1. **Clone the repository:**
```sh
git clone https://github.com/cyanheads/nws-weather-mcp-server.git
```
2. **Navigate into the directory:**
```sh
cd nws-weather-mcp-server
```
3. **Install dependencies:**
```sh
bun install
```
## 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
- **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
```
## Project structure
| Directory | Purpose |
|:----------|:--------|
| `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. |
## 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`
## Contributing
Issues and pull requests are welcome. Run checks before submitting:
```sh
bun run devcheck
bun run test
```
## License
Apache-2.0 — see [LICENSE](LICENSE) for details.