# usgs-water-mcp-server MCP server

Query real-time and historical USGS water data from ~8,000 stream gages and groundwater wells.

## Links
- Registry page: https://www.getdrio.com/mcp/io-github-cyanheads-usgs-water-mcp-server
- Repository: https://github.com/cyanheads/usgs-water-mcp-server

## Install
- Command: `npx -y @cyanheads/usgs-water-mcp-server`
- Endpoint: https://usgs-water.caseyjhand.com/mcp
- Auth: Not captured

## Setup notes
- Package: Npm @cyanheads/usgs-water-mcp-server v0.1.2
- Environment variable: USGS_USER_AGENT
- Environment variable: USGS_REQUEST_TIMEOUT_MS (default 30000)
- Environment variable: MCP_LOG_LEVEL (default info)
- Package: Npm @cyanheads/usgs-water-mcp-server v0.1.2
- Environment variable: USGS_USER_AGENT
- Environment variable: USGS_REQUEST_TIMEOUT_MS (default 30000)
- Environment variable: MCP_HTTP_HOST (default 127.0.0.1)
- Environment variable: MCP_HTTP_PORT (default 3010)
- Environment variable: MCP_HTTP_ENDPOINT_PATH (default /mcp)
- Environment variable: MCP_AUTH_MODE (default none)
- Environment variable: MCP_LOG_LEVEL (default info)
- Remote endpoint: https://usgs-water.caseyjhand.com/mcp

## Tools
- water_list_parameters (Water List Parameters) - List well-known USGS parameter codes with human-readable names, units, and thematic domain — a static, built-in catalog. 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. Endpoint: https://usgs-water.caseyjhand.com/mcp
- water_find_sites (Water Find Sites) - Find USGS water monitoring sites by bounding box, state, county, or HUC watershed code, filtered by site type and parameter availability. Returns site numbers, names, coordinates, types, altitude, and (in expanded mode) drainage area. Call this first — water_get_readings, water_get_series, and water_get_conditions all require a site number. Capped at 500 sites inline; when truncated=true, upstreamTotal holds the full count and, if DataCanvas is enabled, the complete match set stages to a canvas (canvas_id/table_name) for retrieval via water_dataframe_query — otherwise narrow the filters to get all matches. Endpoint: https://usgs-water.caseyjhand.com/mcp
- water_get_readings (Water Get Readings) - Get the latest instantaneous (~15-min, real-time) values for up to 100 USGS sites in one call — per-site, per-parameter records with timestamp, value, unit, and provisional/approved qualifiers. Each series returns only its 10 most recent records (totalValues reports the true count; truncated=true if any were capped); use water_get_series for a full date-range series. Sites NWIS returns nothing for are listed in missingSites, not dropped silently. Use water_find_sites first to discover site numbers and available parameters. Endpoint: https://usgs-water.caseyjhand.com/mcp
- water_get_series (Water Get Series) - Get a daily or instantaneous time series for one USGS site and parameter over a date range, as time-ordered value records. Large sets (>500 records) return the most recent 500 with truncated=true; with DataCanvas enabled they instead spill to a canvas (canvas_id/table_name) for SQL via water_dataframe_query. Use water_find_sites and water_list_parameters to resolve inputs. Endpoint: https://usgs-water.caseyjhand.com/mcp
- water_get_conditions (Water Get Conditions) - Get a USGS site's current reading ranked against its full period-of-record daily-mean percentiles for the same calendar day — a "how unusual is this" percentileClass (record-high to record-low), not a flood-stage or drought determination (this tool fetches no authoritative thresholds). The reading is instantaneous but the percentiles are daily-mean, so the ranking is approximate (see historicalContext.comparisonBasis). When the record is too short to rank, returns the reading with historicalContext=null instead of an error. Use water_find_sites and water_list_parameters to resolve inputs. Endpoint: https://usgs-water.caseyjhand.com/mcp
- water_dataframe_query (Water Dataframe Query) - Run a read-only SQL SELECT against water data tables staged on a DataCanvas by water_get_series or water_find_sites. Workflow: run water_get_series or water_find_sites (get canvas_id + table_name) → water_dataframe_describe (confirm the table and its columns) → water_dataframe_query (SQL analysis). Only SELECT statements are permitted. At most 10,000 rows are returned; a query matching more is capped and the response sets truncated=true — scope with WHERE/LIMIT, and use SELECT COUNT(*) or water_dataframe_describe to learn the true match count. Requires DataCanvas to be enabled on this server instance. Returns an error if DataCanvas is not available. Endpoint: https://usgs-water.caseyjhand.com/mcp
- water_dataframe_describe (Water Dataframe Describe) - List tables and columns staged on a DataCanvas by water_get_series or water_find_sites. Call this after water_get_series or water_find_sites 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. Endpoint: https://usgs-water.caseyjhand.com/mcp

## Resources
- usgs-water://parameters - usgs-water-parameters Full USGS parameter code catalog — injectable context for clients that support resources. Lists well-known parameter codes with human-readable names, units, and thematic domain. The same data is also available via the water_list_parameters tool. MIME type: application/json
- usgs-water://site/01646500 - usgs-water-site Site metadata for a USGS monitoring site: name, coordinates, type, HUC watershed code, state, county, drainage area, and altitude. Use water_find_sites to discover site numbers. MIME type: application/json
- usgs-water://site/14211720 - usgs-water-site Site metadata for a USGS monitoring site: name, coordinates, type, HUC watershed code, state, county, drainage area, and altitude. Use water_find_sites to discover site numbers. MIME type: application/json
- usgs-water://site/09380000 - usgs-water-site Site metadata for a USGS monitoring site: name, coordinates, type, HUC watershed code, state, county, drainage area, and altitude. Use water_find_sites to discover site numbers. MIME type: application/json

## Prompts
Not captured

## Metadata
- Owner: io.github.cyanheads
- Version: 0.1.2
- Runtime: Npm
- Transports: STDIO, HTTP
- License: Not captured
- Language: Not captured
- Stars: Not captured
- Updated: Jun 6, 2026
- Source: https://registry.modelcontextprotocol.io