NWS Weather + USGS Water MCP

An MCP server combining National Weather Service alerts and forecasts with modern USGS water data. Weather comes from api.weather.gov; water data uses the official Python dataretrieval.waterdata module and APIs under api.waterdata.usgs.gov. It does not call legacy waterservices.usgs.gov endpoints.

No API key is required. A persistent local cache reduces repeated calls while keeping live readings fresh.

Why this server

• One MCP for weather and water: correlate forecasts and alerts with nearby gauges without configuring separate services.

• Current USGS stack: all water retrieval uses modern Water Data APIs—not waterservices.usgs.gov.

• Keyless by default: NWS needs an identifying User-Agent, but neither data source requires credentials.

• Public-API friendly: bounded queries and source-specific SQLite TTLs reduce repeat traffic without letting safety data become stale.

• MCP-ready results: every data response is bounded, structured, JSON-safe, and explicit about cache state and truncation.

Related MCP server: stormscope

Weather tools

get_active_alerts is the highest-priority safety tool. An empty successful result means NWS reports no active alerts for that point; it is not an error.

Water tools

The primary tools use domain-friendly names and sensible USGS parameter-code defaults:

get_flood_stage reports only thresholds published in the USGS time-series metadata. It does not invent a flood threshold when a site has none.

The server also exposes generic tools for monitoring locations, time series, continuous and daily observations, latest values, field measurements, peaks, statistics, water-quality samples, reference tables, and collection queryables. Use get_server_info to discover supported collections and common parameter codes. Use get_cache_info and clear_cache to inspect or reset local caching.

Complete tool index

Install and run

Python 3.10 or newer and uv are recommended.

Run directly from the GitHub source without a permanent installation:

uvx --from git+https://github.com/wylieswanson/nws-weather-usgs-water-mcp.git \
  nws-weather-usgs-water-mcp

From a source checkout:

uv sync --frozen
uv run nws-weather-usgs-water-mcp

Run those commands from a source checkout. Press Ctrl-C to stop the stdio server.

The server uses stdio transport and runs without credentials. GeoPandas is not required; geometries are returned as JSON coordinate arrays.

Results default to 200 rows and are capped at 5,000 rows. Change the process cap only when needed:

USGS_WATERDATA_MAX_ROWS=10000 uv run nws-weather-usgs-water-mcp

MCP client configuration

Use an absolute path to this checkout:

{
  "mcpServers": {
    "nws-weather-usgs-water-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/nws-weather-usgs-water-mcp",
        "run",
        "nws-weather-usgs-water-mcp"
      ],
      "env": {
        "NWS_USER_AGENT": "nws-weather-usgs-water-mcp (you@example.com)"
      }
    }
  }
}

Neither API requires a key. NWS requires an identifying User-Agent; the server supplies one automatically, and NWS_USER_AGENT lets you provide the recommended application/contact value. If a deployment later needs higher USGS limits, add "API_USGS_PAT": "your_key" to the same env object. That optional key is sent only to USGS in the X-Api-Key header and is never cached.

Local caching

Successful results are cached in a per-user SQLite database. SQLite provides safe access when several MCP client processes share the cache, and a cache failure never prevents a live API request.

Each tool result includes a cache object with hit, age_seconds, and ttl_seconds. Only successful responses are cached; API errors are not.

The get_cache_info MCP tool reports the active path and entry count; clear_cache deletes all cached responses.

Examples

Ask an MCP client:

• “Are there active alerts at 34.62, -111.25?”

• “Give me the next 24 hourly forecast periods at Bull Pen trailhead.”

• “Get the latest Flagstaff forecast discussion.”

• “Find streamflow gauges within 20 miles of 33.45, -112.07.”

• “What is the current flow at USGS site 01646500?”

• “How abnormal is the current flow at Fossil Creek site 09507480?”

• “How does West Clear Creek’s current flow compare with its record flood?”

• “Give me mean daily flow at 01646500 from 2026-06-01 through 2026-06-30.”

• “What are the current gage height and published flood stage at 01646500?”

• “Is West Clear Creek at 09505800 rising over the last six hours?”

• “When are sunrise, sunset, and civil dusk at 34.62, -111.25?”

• “Find sites containing ‘Salt River’ in Arizona.”

Bare USGS site numbers such as 01646500 are automatically normalized to modern monitoring-location IDs such as USGS-01646500. Time-series values can be provisional, so consumers should retain approval_status and qualifier.

Flow-anomaly results retain the arithmetic ratio at low magnitudes but add ratio_reliable and a percentile-led flow_state. When the day-of-year median is below MIN_RELIABLE_MEDIAN_CFS, consumers should rank or alert from flow_state and percentile_bucket, not the raw ratio. Classified states are high, above_normal, normal, below_normal, low, and negligible; flow_state is null only when no current observation exists to classify.

Stage-trend results group observations by time_series_id, compute each trend independently, and return only the series with the largest rise. This prevents primary and bubbler stages at different datums from corrupting change and rate calculations. approval_status and qualifier remain attached to the selected series. get_water_temperature retains the upstream value and unit_of_measure fields and adds value_c and value_f conveniences.

Peak-flow results return one normalized discharge peak per water year. The metadata.summary object contains the record peak, its date, years of record, median annual peak, latest flow, and current_vs_record. It also groups those annual records by the calendar month of peak_date: monsoon defaults to July–September and cool season to October–June. Each season includes its peak, peak date, median, and qualifying-year count; current_vs_monsoon_record compares the latest flow with the configured monsoon record. Override the monsoon months with USGS_PEAK_MONSOON_MONTHS using comma-separated months or inclusive ranges such as 6-9; the cool season is always the complement. Historical peaks are cached independently from the fresher current-flow reading.

Sun times are calculated locally with Astral. Coordinates resolve to an IANA timezone through the bundled timezonefinder data unless tz is supplied. Every event has both _local and _utc ISO timestamps; no external API is called and the tool does not estimate a canyon-specific latest safe start.

Result shape

Data tools return a consistent envelope designed for MCP clients:

{
  "data_type": "current_flow",
  "row_count": 1,
  "columns": ["monitoring_location_id", "time", "value", "unit_of_measure"],
  "max_rows_reached": false,
  "records": [{"monitoring_location_id": "USGS-01646500", "value": 1234}],
  "metadata": {"source_url": "https://api.waterdata.usgs.gov/..."},
  "cache": {"enabled": true, "hit": false, "age_seconds": 0, "ttl_seconds": 600}
}

Fields within records vary by source collection. max_rows_reached tells the client that it should narrow the query or deliberately request a larger bound. Missing pandas values serialize as JSON null; timestamps use ISO 8601 and geometries are plain coordinate arrays.

Data source and stability

This project targets api.weather.gov and the versioned modern endpoints at api.waterdata.usgs.gov, including the OGC API v0 collections. Those APIs can evolve, so pin this package by release and review the changelog before upgrading. NWS and USGS remain authoritative; this server only retrieves, composes, bounds, caches, and serializes their data.

Development

uv sync --extra dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run pyright

The service layer is separate from the MCP registration layer, allowing unit tests to validate filtering, row caps, site-ID normalization, and JSON-safe serialization without network calls.

Other Python services can reuse the same validated operations without starting an MCP subprocess:

from nws_weather_usgs_water_mcp import operations

result = operations.get_current_flow("09507480")

operations.py is the supported protocol-neutral facade. server.py is the MCP adapter; HTTP applications should not call it through stdio or JSON-RPC.

See CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md before publishing or contributing. Coding agents should also follow AGENTS.md; Claude-specific project context is in CLAUDE.md.