usgs-water-mcp-server

io.github.cyanheads/usgs-water-mcp-serverVersion 0.6.0

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

Status

Responds568 msNov 14, 2026, 14:48 UTCAnswered our handshake without sign-in.

Registry data may be out of date

We could not refresh it, so this page shows the last copy.

Last checked: Nov 14, 2026, 14:48 UTC
Latency: 568 ms
Remotes responding: 1 of 1
Sign-in: No sign-in
Hosting: Hosted outside the EU (detected)
Registry data as of: Nov 14, 2026, 22:14 UTC

Data from the official MCP Registry, checked by run.zero. How we check

Connect

Streamable HTTP

https://usgs-water.caseyjhand.com/mcpResponds568 msNov 14, 2026, 14:48 UTC

No sign-in

Claude Code

claude mcp add --transport http usgs-water-mcp-server https://usgs-water.caseyjhand.com/mcp

Claude Desktop and claude.ai

1
2
3

Settings > Connectors > Add custom connector
Name: usgs-water-mcp-server
Remote MCP server URL: https://usgs-water.caseyjhand.com/mcp

Cursor

{
  "mcpServers": {
    "usgs-water-mcp-server": {
      "url": "https://usgs-water.caseyjhand.com/mcp"
    }
  }
}

VS Code

code --add-mcp '{"name":"usgs-water-mcp-server","type":"http","url":"https://usgs-water.caseyjhand.com/mcp"}'

Streamable HTTP

npm: @cyanheads/usgs-water-mcp-server 0.6.0

Package only

npm (npx)

claude mcp add usgs-water-mcp-server -- npx -y @cyanheads/usgs-water-mcp-server@0.6.0

Streamable HTTP

npm: @cyanheads/usgs-water-mcp-server 0.6.0

Package only

npm (npx)

claude mcp add usgs-water-mcp-server -- npx -y @cyanheads/usgs-water-mcp-server@0.6.0

Built your own server? run.zero hosts MCP servers on European infrastructure.

Host your own MCP server on run.zero

Tools

8 tools

Tools of usgs-water-mcp-server
	Description		Read-only	Idempotent	Open world
`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, or to water_dataframe_drop (when this server enables it) to remove a table you no longer need. 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 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, or to water_dataframe_drop (when this server enables it) to remove a table you no longer need. Requires DataCanvas to be enabled on this server instance. Returns an error if DataCanvas is not available.	Not declared	Yes	Yes	No
`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), then optionally water_dataframe_drop (when this server enables it) to remove a table you are done with. 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.	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), then optionally water_dataframe_drop (when this server enables it) to remove a table you are done with. 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.	Not declared	Yes	Yes	No
`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, the UTC time each site last reported (lastObservedAt), and (in expanded mode) drainage area. Call this first — water_get_readings, water_get_series, and water_get_conditions all require a site number. Supply exactly one major filter — bbox, stateCd, countyCd, or huc; siteType, parameterCd, hasDataTypeCd, and observedWithin only narrow within it and cannot stand alone. parameterCd and hasDataTypeCd match sites that have ever reported, discontinued ones included; set observedWithin to keep only sites reporting now. Page through matches with limit/offset (500 per page); truncated=true means matches remain after the returned window and upstreamTotal holds the full count. When the match set exceeds 500 and DataCanvas is enabled, the complete set also stages to a canvas (canvas_id/table_name) — inspect it with water_dataframe_describe, then retrieve it with water_dataframe_query.	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, the UTC time each site last reported (lastObservedAt), and (in expanded mode) drainage area. Call this first — water_get_readings, water_get_series, and water_get_conditions all require a site number. Supply exactly one major filter — bbox, stateCd, countyCd, or huc; siteType, parameterCd, hasDataTypeCd, and observedWithin only narrow within it and cannot stand alone. parameterCd and hasDataTypeCd match sites that have ever reported, discontinued ones included; set observedWithin to keep only sites reporting now. Page through matches with limit/offset (500 per page); truncated=true means matches remain after the returned window and upstreamTotal holds the full count. When the match set exceeds 500 and DataCanvas is enabled, the complete set also stages to a canvas (canvas_id/table_name) — inspect it with water_dataframe_describe, then retrieve it with water_dataframe_query.	Not declared	Yes	Yes	Yes
`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). Rankings follow the water level: for a depth-to-water code (72019) a shallower depth ranks higher. 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. A reading USGS reports as no data (a seasonal, discontinued, dry, or malfunctioning gage) returns an empty currentValue with the qualifiers naming why, and is not ranked. When the site measures the parameter with several sensors (methods), one reading is used and named by methodId/methodDescription — from a sensor the statistics hold a daily-mean series for when one is, otherwise the most recent across them; water_get_readings lists every method. Use water_find_sites and water_list_parameters to resolve inputs.	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). Rankings follow the water level: for a depth-to-water code (72019) a shallower depth ranks higher. 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. A reading USGS reports as no data (a seasonal, discontinued, dry, or malfunctioning gage) returns an empty currentValue with the qualifiers naming why, and is not ranked. When the site measures the parameter with several sensors (methods), one reading is used and named by methodId/methodDescription — from a sensor the statistics hold a daily-mean series for when one is, otherwise the most recent across them; water_get_readings lists every method. Use water_find_sites and water_list_parameters to resolve inputs.	Not declared	Yes	Yes	Yes
`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. Omitting parameterCd returns every parameter each site publishes. A site measuring one parameter with several sensors returns one series per sensor, each named by methodId (its time-series ID) and methodDescription; a sensor that reported nothing in the period still returns, with totalValues 0. At most 100 series return per call — every site that returned a series keeps at least one, and totalSeries reports how many the upstream returned; pass parameterCd or split the sites across calls to reach the rest. Each series returns only its 10 most recent records (totalValues reports the true count); truncated=true when either cap applied. Use water_get_series for a full date-range series. Sites that return no series are listed in missingSites, not dropped silently. Find site numbers with water_find_sites; water_get_site_data_catalog lists the parameters and sensors a site measures and when each last reported.	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. Omitting parameterCd returns every parameter each site publishes. A site measuring one parameter with several sensors returns one series per sensor, each named by methodId (its time-series ID) and methodDescription; a sensor that reported nothing in the period still returns, with totalValues 0. At most 100 series return per call — every site that returned a series keeps at least one, and totalSeries reports how many the upstream returned; pass parameterCd or split the sites across calls to reach the rest. Each series returns only its 10 most recent records (totalValues reports the true count); truncated=true when either cap applied. Use water_get_series for a full date-range series. Sites that return no series are listed in missingSites, not dropped silently. Find site numbers with water_find_sites; water_get_site_data_catalog lists the parameters and sensors a site measures and when each last reported.	Not declared	Yes	Yes	Yes
`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. A site can hold several series for one query — one per daily statistic (mean, maximum, minimum) and one per sensor (method); this returns one, reporting its statCd and methodId (its time-series ID), and lists the rest in otherSeries so any can be re-requested with the statCd and methodId inputs. By default it returns the daily mean when one carries values, and the method with the most records. Large sets (>500 records) return the most recent records inline with truncated=true — the last 500 without DataCanvas, and with DataCanvas enabled the complete series also spills to a canvas (canvas_id/table_name): inspect the staged table with water_dataframe_describe, then read the full series with water_dataframe_query. Use water_find_sites and water_list_parameters to resolve inputs; water_get_site_data_catalog lists a site’s series with their record bounds (beginDate/endDate), and a row’s timeSeriesId works as methodId.	Get a daily or instantaneous time series for one USGS site and parameter over a date range, as time-ordered value records. A site can hold several series for one query — one per daily statistic (mean, maximum, minimum) and one per sensor (method); this returns one, reporting its statCd and methodId (its time-series ID), and lists the rest in otherSeries so any can be re-requested with the statCd and methodId inputs. By default it returns the daily mean when one carries values, and the method with the most records. Large sets (>500 records) return the most recent records inline with truncated=true — the last 500 without DataCanvas, and with DataCanvas enabled the complete series also spills to a canvas (canvas_id/table_name): inspect the staged table with water_dataframe_describe, then read the full series with water_dataframe_query. Use water_find_sites and water_list_parameters to resolve inputs; water_get_site_data_catalog lists a site’s series with their record bounds (beginDate/endDate), and a row’s timeSeriesId works as methodId.	Not declared	Yes	Yes	Yes
`water_get_site_data_catalog`Discover a USGS site’s parameters, sensors, statistics, and UTC record bounds before calling water_get_series. Find site numbers with water_find_sites. Each row is a distinct series; metadata bounds may contain gaps and lag observations. For water_get_series, take YYYY-MM-DD from beginDate/endDate, pass statCd only for daily rows, and pass a row’s timeSeriesId as methodId to request that exact series (water_get_readings and water_get_series report the same ID as methodId). Rows with null seriesType are other computations and cannot be requested with water_get_series. Follow nextCursor with the same filters and limit until null.	Discover a USGS site’s parameters, sensors, statistics, and UTC record bounds before calling water_get_series. Find site numbers with water_find_sites. Each row is a distinct series; metadata bounds may contain gaps and lag observations. For water_get_series, take YYYY-MM-DD from beginDate/endDate, pass statCd only for daily rows, and pass a row’s timeSeriesId as methodId to request that exact series (water_get_readings and water_get_series report the same ID as methodId). Rows with null seriesType are other computations and cannot be requested with water_get_series. Follow nextCursor with the same filters and limit until null.	Not declared	Yes	Yes	Yes
`water_list_parameters`Look up USGS parameter codes — the 5-digit codes every other tool's parameterCd takes. With no query, lists a curated set of well-known codes with names, units, and thematic group, from a built-in table (no network call): 00060 = "Discharge" (ft³/s), 00065 = "Gage height" (ft), 00010 = "Temperature, water" (°C), 72019 = "Depth to water level" (ft), and others; filter it with group. For anything else — turbidity, nitrate, chlorophyll, suspended sediment, salinity — pass query to search the full USGS parameter-code catalog (~19,600 codes) by name and description, or pass a 5-digit code to look it up. A query returns at most 25 entries, matching curated codes first, with total counting every match.	Look up USGS parameter codes — the 5-digit codes every other tool's parameterCd takes. With no query, lists a curated set of well-known codes with names, units, and thematic group, from a built-in table (no network call): 00060 = "Discharge" (ft³/s), 00065 = "Gage height" (ft), 00010 = "Temperature, water" (°C), 72019 = "Depth to water level" (ft), and others; filter it with group. For anything else — turbidity, nitrate, chlorophyll, suspended sediment, salinity — pass query to search the full USGS parameter-code catalog (~19,600 codes) by name and description, or pass a 5-digit code to look it up. A query returns at most 25 entries, matching curated codes first, with total counting every match.	Not declared	Yes	Yes	Yes

Details

Registry status: Active
Published: Nov 11, 2026
Updated: Nov 11, 2026
Website: Not given
Repository: https://github.com/cyanheads/usgs-water-mcp-server⁠ (opens in a new tab)
Categories: Uncategorized
GDPR: Not declared

Are you the operator? Claim this listing