Skip to main content
Glama
README.md
# nws-mcp

An [MCP](https://modelcontextprotocol.io) server for US weather, backed by the [National Weather Service API](https://www.weather.gov/documentation/services-web-api). Forecasts, hourly forecasts, active alerts, current observations, and the raw grid metadata behind them.

**No API key.** Both upstream services — api.weather.gov and the US Census geocoder — are public and keyless, so this runs a minute after cloning with nothing to sign up for.

```
You: is it going to rain in Tucson tonight?

Assistant: [get_forecast place="Tucson, AZ" periods=2]
             -> This Afternoon: 96°F, W 5 mph, 5% precip, Mostly Sunny
                Tonight: 73°F, SSW 5 mph, 5% precip, Partly Cloudy

           [get_active_alerts state="AZ"]
             -> Flood Advisory (Minor), Pima County, expires 6:30 PM
                Extreme Heat Watch (Severe), Tucson Metro Area

           Probably not — tonight is only 5% precipitation and partly
           cloudy. There is an active Flood Advisory for Pima County
           until 6:30 PM from earlier storms, and an Extreme Heat Watch
           running through next week worth knowing about.
```

## Tools

| Tool | What it does |
|------|--------------|
| `get_forecast` | Multi-day forecast as named periods ("Tonight", "Saturday") with temperature, wind, and a short description. 1–14 periods, default 6. |
| `get_hourly_forecast` | Hour-by-hour temperature, precipitation probability, and wind. 1–48 hours, default 12. |
| `get_active_alerts` | Active alerts, watches, and warnings for a point or a whole state. Says "No active alerts" rather than returning an empty response. |
| `get_current_conditions` | Latest observation from the nearest station: temperature, wind, humidity, pressure, visibility — plus the station id and how old the reading is. |
| `get_grid_info` | The point-metadata lookup itself: forecast office, grid cell, radar station, forecast and county zones. |

Every tool takes either `place` (a `"City, ST"` string or a full street address, geocoded internally) **or** `latitude` + `longitude`, and a `response_format` of `markdown` (default) or `json`.

All five are annotated `readOnlyHint: true` and `openWorldHint: true`.

## Quickstart

Requires Node 18+ (for native `fetch`).

```bash
git clone https://github.com/Enrique-S-J/nws-mcp.git
cd nws-mcp
npm install
npm run build
```

The server speaks stdio and is launched by its client, so running `npm start` yourself just blocks waiting for JSON-RPC on stdin. Point a client at it instead.

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/absolute/path/to/nws-mcp/dist/index.js"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add weather -- node /absolute/path/to/nws-mcp/dist/index.js
```

The path must be absolute, and it must point at `dist/index.js` — the built output, not `src/index.ts`. Works with any MCP client that supports stdio transport.

## Design notes

The decisions that took the most thought, since a weather API is a deceptively simple thing to wrap.

- **The forecast is a two-step lookup, and that's why there's a cache.** NWS publishes forecasts per *grid cell*, not per coordinate. Getting a forecast means calling `/points/{lat},{lon}` to learn which cell you're in, then following the `forecast` URL out of that response — you can't construct the second URL yourself. That doubles the request count for every forecast, so points metadata is cached for 24 hours. The grid mapping is fixed geography; it changes when NWS redraws its grids, which is essentially never. Forecasts are cached 10 minutes, observations 5, alerts 60 seconds, geocodes a day. TTLs come from how fast each thing can actually change rather than one global number, because caching alerts as aggressively as grid metadata would be dangerous and caching grid metadata as briefly as alerts would be wasteful.

- **NWS requires a User-Agent, and it's a courtesy request as much as a technical one.** Requests without one may be rejected. This server sends `nws-mcp (github.com/Enrique-S-J/nws-mcp)` on every call, which identifies the software and gives NWS someone to contact if it misbehaves. In the same spirit, outbound requests are gated to two concurrent and 5xx responses get exactly one retry with backoff. The API is free, unauthenticated, and paid for with tax money; that's a reason for restraint, not an invitation.

- **Errors are a taxonomy, not a string.** Four kinds, each implying a different next move: `geocode-no-match` (the place name didn't resolve — try "City, ST" or coordinates), `outside-coverage` (NWS 404s the point — it's a US-only service), `upstream-error` (NWS 5xx — probably transient, retry), and `network-failure` (couldn't reach the host at all). The messages say what to do, not just what broke: a bad location tells you the two argument forms that work. Nothing throws across the MCP boundary — tool failures come back as `isError: true` content, because a model can act on "that's outside US coverage" and can't act on a stack trace.

- **Geocoding needs two services, because the Census runs two.** The obvious choice, the Census `onelineaddress` geocoder, resolves street addresses — and returns **zero matches** for `"Tucson, AZ"`, because it wants a house number. Named places live in a different dataset, the TIGERweb place gazetteer. So the input is classified first: `"City, ST"` goes to the gazetteer (incorporated places, then Census Designated Places for unincorporated communities), anything else goes to the address geocoder, and each falls back to the other since the classification is a heuristic. Both are keyless and US-only.

- **Observation age is part of the reading.** A station can go quiet for hours while the API happily returns its last value. `get_current_conditions` reports the station id and the age in minutes, and warns explicitly when a reading is over two hours old. "82°F" means something different when it was measured three hours ago, and that difference is operationally relevant.

- **Units are converted, because NWS is inconsistent about them.** Forecast endpoints return Fahrenheit and `"5 mph"` strings. The observation endpoint returns SI regardless — degrees C, km/h, pascals, meters. Everything is normalized to imperial so the two don't disagree inside the same conversation. Fields the station didn't report stay `null` rather than becoming zero, and the markdown renderer omits them instead of printing a confident `0 mph`.

- **Types are narrow on purpose.** Every interface declares only the fields actually read, and critical ones are hand-validated with actionable messages ("NWS returned no forecast URL for this point; the location may be outside NWS coverage"). A 200 response with a missing `forecast` URL is a real case — it's what a point just outside coverage looks like — and it should produce an explanation, not a `TypeError` three frames later.

## Testing

```bash
npm test
```

53 tests across three suites, all offline:

- **`nws.test.ts`** — the points→forecast chain, cache hits and misses, that failures are *not* cached, retry-once-on-5xx and no-retry-on-4xx, the User-Agent header, unit conversion, observation age math, and null-field handling.
- **`geocode.test.ts`** — gazetteer vs. address routing, the CDP fallback, SQL quote escaping, response-shape drift, and that a bare city never hits the address geocoder.
- **`tools.test.ts`** — the MCP layer itself, driven through a real client over an in-memory transport: tool registration, read-only annotations, that every argument carries a description, the location-argument rules, and markdown/json parity. A tool whose schema no client can satisfy passes a direct function call and fails in Claude Desktop, so the boundary worth testing is the one it's consumed through.

**Tests mock `fetch` and never touch the network.** Three reasons: determinism (a test that fails because it's not raining is not a test), CI safety (no external dependency in the build), and courtesy — hammering a free public service on every push is rude, and mocking is what lets the suite run in about a second.

For the network path there's a separate live check:

```bash
npm run build && npm run smoke
```

It spawns the built server over real stdio MCP and runs initialize → tools/list → forecast → conditions → alerts → an out-of-coverage error path against the live API.

**Verified 2026-08-14:** `npm run build` clean, all 53 tests passing, and the live smoke test completed successfully against api.weather.gov and the Census services on macOS with Node 22.17.1.

## Roadmap

- Zone-based alerts (`/alerts/active/zone/{zoneId}`) for people who think in NWS zones
- Forecast discussions (`/products/types/AFD`) — the meteorologist's own reasoning, which is often more useful than the numbers
- An MCP resource exposing the raw gridpoint data for models that want to do their own interpretation

## License

MIT

TDQS

A3.8/5.0

Scored across 5 tools

Disambiguation5/5

Each tool targets a distinct data product: multi-day forecast, hourly forecast, active alerts, latest observation, and grid metadata. The only near-neighbor pair (get_forecast vs get_hourly_forecast) is unambiguously separated by name and by the explicit 'multi-day periods' vs 'hour-by-hour' descriptions.

Naming Consistency5/5

All five tools follow a strict snake_case get_<resource> pattern with no verb or casing deviations. The naming reads predictably and maps cleanly onto the returned resource.

Tool Count5/5

Five tools is well within the well-scoped range, and each tool maps to a genuinely different NWS endpoint with no redundant overlap. Nothing feels padded or missing at the count level.

Completeness4/5

The core weather surface (daily forecast, hourly forecast, current conditions, alerts, grid metadata) is fully covered with no dead ends for typical use. Minor gaps exist around historical observations, station search, and narrative forecast-discussion text products, which agents would have to work around.

Maintenance

ActivityInactive
ResponsivenessNo recent community issues