nws-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nws-mcp what's the forecast for Denver this weekend?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Multi-day forecast as named periods ("Tonight", "Saturday") with temperature, wind, and a short description. 1–14 periods, default 6. |
| Hour-by-hour temperature, precipitation probability, and wind. 1–48 hours, default 12. |
| Active alerts, watches, and warnings for a point or a whole state. Says "No active alerts" rather than returning an empty response. |
| Latest observation from the nearest station: temperature, wind, humidity, pressure, visibility — plus the station id and how old the reading is. |
| 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 buildThe 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.jsThe 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 theforecastURL 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), andnetwork-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 asisError: truecontent, 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
onelineaddressgeocoder, 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_conditionsreports 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 staynullrather than becoming zero, and the markdown renderer omits them instead of printing a confident0 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
forecastURL is a real case — it's what a point just outside coverage looks like — and it should produce an explanation, not aTypeErrorthree frames later.
Testing
npm test53 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 smokeIt 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 zonesForecast discussions (
/products/types/AFD) — the meteorologist's own reasoning, which is often more useful than the numbersAn MCP resource exposing the raw gridpoint data for models that want to do their own interpretation
License
MIT
Available Tools
5 toolsget_active_alertsGet active weather alertsARead-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 conditionsARead-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 forecastARead-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 infoARead-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 forecastBRead-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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
US weather & geo for AI agents: forecasts, alerts, earthquakes, elevation, geocoding. No keys.
US weather & geo for AI agents: forecasts, alerts, earthquakes, elevation, geocoding. No keys.
US NWS weather alerts and 5-day forecasts for AI agents. $0.01 per call.
Get US weather forecasts, active and recent alerts, and current observations.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to access real-time US weather forecasts and alerts through the National Weather Service API.213 npmMIT
- FlicenseNot gradedqualityDmaintenanceProvides real-time weather alerts and forecasts from the National Weather Service for US locations, integrating with AI assistants via the Model Control Protocol.-
- AlicenseNot gradedqualityDmaintenanceProvides weather forecasts and alerts for US locations via the National Weather Service API, enabling AI assistants to deliver real-time weather information.28 npmISC
- AlicenseAqualityBmaintenanceProvides 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.6MIT