@cyanheads/usgs-water-mcp-server

Static lookup of well-known USGS parameter codes with human-readable names, units, and thematic domain. No network call. Use this first to discover that 00060 = "Discharge" (ft³/s), 00065 = "Gage height" (ft), 00010 = "Temperature, water" (°C), 72019 = "Depth to water level" (ft), etc. Filter by group to narrow results.

Find USGS water monitoring sites by bounding box, state, county, or HUC watershed code. Filter by site type (stream gage, groundwater well, lake) and parameter availability. Returns site numbers, names, coordinates, types, and (in expanded mode) drainage area and altitude. Call this first to discover site numbers — water_get_readings, water_get_series, and water_get_conditions all require a site number. To check which parameters or data types a site carries, use the parameterCd or hasDataTypeCd filters. Results are capped at 500 sites; when truncated=true the full upstream count is in upstreamTotal — narrow the query with bbox, countyCd, huc, siteType, parameterCd, or hasDataTypeCd to get all matches.

Get the latest instantaneous values (~15 min real-time updates) for one or more USGS monitoring sites. Returns per-site, per-parameter records including timestamp, value, unit, and provisional/approved qualifiers. Accepts up to 100 site numbers in one call. Use water_find_sites first to discover valid site numbers and available parameter codes. Groundwater depth is available via parameterCd=72019 (Depth to water level, ft below land surface). For a date-range time series, use water_get_series instead.

Get a time series of daily or instantaneous values for a USGS site and parameter over a date range. Returns siteNumber, parameterCd, and time-ordered value records. When the server has DataCanvas enabled, large result sets (>500 records) spill to a canvas — the response includes canvas_id and table_name for SQL analysis via water_dataframe_query. Without DataCanvas, returns the most recent 500 records with truncated=true. Use water_find_sites to discover valid site numbers. Use water_list_parameters for parameter codes.

Get current hydrologic conditions at a USGS site, placed in historical context. Returns today's current reading alongside a percentile classification (record-high, above-normal, normal, below-normal, low, record-low) derived from the full period-of-record daily statistics. Answers "is this flooding or drought?" — not just a raw number. Use water_find_sites to discover site numbers; use water_list_parameters to find parameter codes. When the site has insufficient record history, returns the current reading with historicalContext=null rather than an error.

Run a read-only SQL SELECT against water time-series tables staged on a DataCanvas by water_get_series. Workflow: water_get_series (get canvas_id + table_name) → water_dataframe_describe (confirm schema) → water_dataframe_query (SQL analysis). Only SELECT statements are permitted. Results are capped at 10,000 rows; use WHERE and LIMIT clauses to stay within budget. Requires DataCanvas to be enabled on this server instance. Returns an error if DataCanvas is not available.

List tables and columns staged on a DataCanvas by water_get_series. Call this after water_get_series returns a canvas_id to discover the exact table name and column types before writing a query. Then pass the table name to water_dataframe_query. Requires DataCanvas to be enabled on this server instance. Returns an error if DataCanvas is not available.