NWS Weather + USGS Water MCP

<!-- mcp-name: io.github.wylieswanson/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.

Weather tools

Tool	Purpose
get_active_alerts	Active NWS watches, warnings, and advisories for a point
get_point_forecast	Multi-period NWS point forecast
get_hourly_forecast	Up to 168 hourly periods with precipitation probability
get_forecast_discussion	Latest raw Area Forecast Discussion from an NWS office
get_wfo_for_point	Resolve a point to its NWS office, grid, and zones

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:

Tool	Purpose
find_gauges	Find nearby gauges that have a latest reading, with exact distance
search_sites	Case-insensitive partial site-name search, optionally by state
get_current_flow	Latest discharge (00060)
get_flow_anomaly	Current discharge compared with this date's median and percentiles
get_daily_flow	Mean daily discharge (00060, statistic 00003)
get_water_level	Latest gage height (00065)
get_water_temperature	Latest water temperature (00010)
get_flood_stage	Latest gage height plus published action/flood thresholds

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

Category	Tools
NWS weather	get_active_alerts, get_point_forecast, get_hourly_forecast, get_forecast_discussion, get_wfo_for_point
Focused USGS water	find_gauges, search_sites, get_current_flow, get_flow_anomaly, get_daily_flow, get_water_level, get_water_temperature, get_flood_stage
General USGS access	search_monitoring_locations, search_time_series, get_observations, get_latest_values, get_field_data, get_statistics, get_water_quality_samples, lookup_reference_data, get_collection_queryables
Server and cache	get_server_info, get_cache_info, clear_cache

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.

Data	Default TTL
NWS active alerts	60 seconds maximum
NWS forecasts and forecast discussions	15 minutes
NWS point-to-grid mapping	7 days
Latest readings, nearby gauges, flood stage, flow anomaly	10 minutes
Continuous observations	10 minutes
Daily observations and USGS statistics	6 hours
Field data and other collections	30 minutes
Samples	1 hour
Site and time-series metadata	6 hours
Reference tables and queryable schemas	24 hours

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

Variable	Purpose
NWS_USGS_CACHE_ENABLED=0	Disable caching
NWS_USGS_CACHE_DIR=/path	Override the OS-specific cache directory
NWS_USGS_CACHE_MAX_ENTRIES=2000	Limit stored query results
NWS_USGS_CACHE_TTL_SECONDS=300	Override defaults; alerts remain capped at 60s
NWS_ALERTS_CACHE_TTL_SECONDS=30	Override alert TTL, capped at 60 seconds
NWS_FORECAST_CACHE_TTL_SECONDS=900	Override forecast TTL
NWS_POINTS_CACHE_TTL_SECONDS=604800	Override point-grid TTL
NWS_DISCUSSION_CACHE_TTL_SECONDS=900	Override discussion TTL
USGS_LATEST_CACHE_TTL_SECONDS=600	Override current/latest-value TTL
USGS_CONTINUOUS_CACHE_TTL_SECONDS=600	Override continuous-observation TTL
USGS_DAILY_CACHE_TTL_SECONDS=21600	Override daily-value TTL
USGS_METADATA_CACHE_TTL_SECONDS=21600	Override site/time-series metadata TTL
USGS_REFERENCE_CACHE_TTL_SECONDS=86400	Override reference/queryable TTL
USGS_STATISTICS_CACHE_TTL_SECONDS=21600	Override statistics TTL
USGS_SAMPLES_CACHE_TTL_SECONDS=3600	Override water-quality sample TTL

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.