Skip to main content
Glama

nws-mcp

An MCP server for US weather, backed by the National Weather Service 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.

Related MCP server: mcp-weather

Quickstart

Requires Node 18+ (for native fetch).

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:

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

Claude Code

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

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:

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

Available Tools

5 tools
get_active_alertsGet active weather alertsA
Read-only

Active National Weather Service alerts, watches, and warnings — for a specific point, or for an entire state with the "state" argument.

Inputs: place, state, latitude, longitude, +1 more.

get_current_conditionsGet current conditionsA
Read-only

Latest observation from the National Weather Service station nearest a US location: temperature, wind, humidity, pressure, visibility, and how old the reading is.

Inputs: place, latitude, longitude, response_format.

get_forecastGet forecastA
Read-only

Multi-day US weather forecast from the National Weather Service. Returns named periods (e.g. "Tonight", "Thursday") with temperature, wind, and a short description.

Inputs: place, periods, latitude, longitude, +1 more.

get_grid_infoGet NWS grid infoA
Read-only

The National Weather Service grid metadata for a US location: forecast office, grid cell, radar station, and forecast/county zones. Useful for understanding which office issues a forecast and for building further NWS API calls.

Inputs: place, latitude, longitude, response_format.

get_hourly_forecastGet hourly forecastB
Read-only

Hour-by-hour US weather forecast from the National Weather Service, with temperature, precipitation probability, and wind for each hour.

Inputs: hours, place, latitude, longitude, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to access real-time US weather forecasts and alerts through the National Weather Service API.
      2
      13 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides real-time weather alerts and forecasts from the National Weather Service for US locations, integrating with AI assistants via the Model Control Protocol.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides weather forecasts and alerts for US locations via the National Weather Service API, enabling AI assistants to deliver real-time weather information.
      28 npm
      ISC
    • A
      license
      A
      quality
      B
      maintenance
      Provides US weather forecasts, current conditions, alerts, earthquakes, elevation, and geocoding via keyless US-government data feeds. Enables AI agents to access real-time weather and geospatial data without API keys.
      6
      MIT