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.

After the package is published to PyPI, run it without a permanent installation:

uvx 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?”

• “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?”

• “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.

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.

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.