Usgs Water Mcp Server

cyanheads/usgs-water-mcp-server

Connects Claude to the USGS Instantaneous Values and Daily Values APIs covering roughly 8,000 stream gages and groundwater monitoring sites across the United States. You get seven tools: discover sites by bounding box or watershed HUC, pull current readings in near real time, fetch historical daily or instantaneous series, and check current conditions against percentile ranks from the full period of record. Large time series automatically spill to DuckDB-backed DataCanvas tables when enabled, so you can run SQL aggregations without truncation. Useful for hydrologic analysis, drought and flood assessment, or any workflow that needs authoritative water data with geographic and temporal filtering. Supports both stdio and streamable HTTP transports, with a public hosted instance available.

GitHub stars: 3
tools: 8
auth: Secret needed
transport: STDIO, HTTP
env vars: 10
last updated: Nov 11, 2026

View on GitHub

Install

From registry metadata

$ npx add-mcp https://usgs-water.caseyjhand.com/mcp --name usgs-water

Run in your terminal. add-mcp asks which agents to add it to (Claude Code, Codex, Cursor and more). Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

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

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 8 tools

Verified live against the running server on Nov 6, 2026.

water_list_parametersLook 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)...2 params

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)...

Parameters* required

groupstring

Filter the curated list by thematic domain: "streamflow", "groundwater", "temperature", "meteorological", "water-quality", or "all" (default). Applies to the curated list only — leave it "all" when...one of streamflow · groundwater · temperature · meteorological · water-quality · alldefault: all

querystring

Search the full USGS parameter-code catalog. Case-insensitive; every word must start a word in the parameter name or description (e.g. "turbidity", "nitrate filtered", "dissolved oxygen"). A bare 5...

water_find_sitesFind 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, wate...11 params

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, wate...

Parameters* required

bboxstring

Bounding box as "west,south,east,north" in decimal degrees (e.g. "-77.5,38.5,-76.5,39.5" for the DC metro area). One of the four major filters — bbox, stateCd, countyCd, and huc are mutually exclus...

canvas_idstring

Canvas ID from a prior call to add this match set as a table on an existing canvas rather than creating a new one. Each distinct filter set gets its own table name, so re-running the identical quer...

countyCdstring

FIPS county code(s) as bare 5-digit numbers — state and county digits concatenated, no separator (e.g. "51013" for Arlington, VA). Comma-separate up to 20 (e.g. "51059,51061"). The 5 digits already...

hasDataTypeCdstring

Require sites with data of this type. Common values: "iv" (real-time/instantaneous), "dv" (daily values), "gw" (groundwater). Comma-separate multiple types.

hucstring

Hydrologic Unit Code (HUC) scoping results to a watershed. Either a 2-digit major HUC (e.g. "02" for the Mid-Atlantic region) or an 8-digit minor HUC (e.g. "02070008" for the Middle Potomac). NWIS...

limitinteger

Maximum sites to return inline, 1–500. Default 500 (the inline cap).default: 500

offsetinteger

Number of matching sites to skip before returning results. Page through matches beyond the inline cap by advancing offset by limit. Default 0.default: 0

parameterCdstring

5-digit parameter code to require at each returned site (e.g. "00060" for discharge). Use water_list_parameters to discover codes. Comma-separate multiple codes with no spaces (e.g. "00060,00065").

siteOutputstring

"basic" returns core identification fields. "expanded" adds drainage area, altitude, contributing area, and other metadata.one of basic · expandeddefault: basic

siteTypestring

Site type filter. Common codes: "ST" (stream), "GW" (groundwater well), "LK" (lake/reservoir), "SP" (spring), "AT" (atmosphere), "OC" (ocean), "ES" (estuary). Comma-separate multiple types (e.g. "S...

stateCdstring

2-character US state abbreviation (e.g. "VA", "WA"). Returns all sites in the state for the given filters. Major filter — supply exactly one of bbox, stateCd, countyCd, huc.

water_get_readingsGet 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...3 params

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

Parameters* required

parameterCdarray

Parameter codes to return. Omit to get every parameter each site publishes — one series per site, parameter, and method, so a large batch can exceed the 100-series cap. Use water_list_parameters to...

periodstring

ISO 8601 duration for the lookback period (e.g. "PT2H" = last 2 hours, "P1D" = last 1 day, "P7D" = last 7 days). Default: "PT2H" (last 2 hours of readings). Widening it raises totalValues, but each...default: PT2H

sites*array

One or more USGS site numbers to query. Maximum 100 per call.

water_get_seriesGet a daily or instantaneous time series for one USGS site and parameter over a date range, as time-ordered value records. NWIS can hold several series for one query — one per daily statistic (mean, maximum, minimum) and one per sensor (method); this returns one, reporting its...8 params

Get a daily or instantaneous time series for one USGS site and parameter over a date range, as time-ordered value records. NWIS can hold several series for one query — one per daily statistic (mean, maximum, minimum) and one per sensor (method); this returns one, reporting its...

Parameters* required

canvas_idstring

Canvas ID from a prior call to add this series as a table on an existing canvas rather than creating a new one. Each distinct site, parameter code, series type, date range, and selected statistic a...

endDate*string

End date in YYYY-MM-DD format (e.g. "2024-12-31").

methodIdstring

NWIS method ID of the sensor series to return — the methodId or an otherSeries[].methodId from a prior response for the same site, parameter, and seriesType. Omit for the method with the most recor...

parameterCd*string

A single 5-digit USGS parameter code (e.g. "00060" for discharge, "00065" for gage height). One code per call — this tool returns one series. Use water_list_parameters to discover available codes.

seriesTypestring

"daily" returns one value per day (DV service, typically mean/max/min). "instantaneous" returns ~15-minute readings (IV service). Default: "daily". Use "instantaneous" for high-resolution analysis.one of daily · instantaneousdefault: daily

site*string

USGS site number (8–15 digits, e.g. "01646500" for Potomac River at Little Falls). Use water_find_sites to discover valid site numbers.

startDate*string

Start date in YYYY-MM-DD format (e.g. "2024-01-01").

statCdstring

Daily statistic to return, as a 5-digit NWIS code: "00003" mean, "00001" maximum, "00002" minimum. Omit for the mean when NWIS returns one with values, otherwise the first statistic that has values...

water_get_site_data_catalogDiscover 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 f...5 params

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 f...

Parameters* required

cursorstring

Opaque nextCursor from the previous page; keep site, parameterCd, seriesType, and limit unchanged.

limitinteger

Maximum metadata rows per page (1–1000; default 100). Keep unchanged when using cursor.default: 100

parameterCdstring

Optional 5-digit parameter code from water_list_parameters, e.g. "00060".

seriesTypestring

Limit to Daily computations or Points/Instantaneous computations. Omit to include all periods.one of daily · instantaneous

site*string

USGS site number (8–15 digits), from water_find_sites; e.g. "01646500".

water_get_conditionsGet 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 thr...2 params

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 thr...

Parameters* required

parameterCd*string

5-digit USGS parameter code (e.g. "00060" for discharge, "00065" for gage height). Use water_list_parameters to discover codes.

site*string

USGS site number (8–15 digits, e.g. "01646500" for Potomac River at Little Falls). Use water_find_sites to discover valid site numbers.

water_dataframe_queryRun 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...2 params

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

Parameters* required

canvas_id*string

Canvas ID returned by water_get_series or water_find_sites. Identifies the canvas holding the data.

sql*string

Read-only SELECT statement. Reference the table by the table_name from water_get_series or water_find_sites; columns vary by source table, so run water_dataframe_describe first for the exact schema...

water_dataframe_describeList 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_datafram...1 params

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_datafram...

Parameters* required

canvas_id*string

Canvas ID returned by water_get_series or water_find_sites. Identifies the canvas to describe.

Configuration

USGS_USER_AGENT

Custom User-Agent string for USGS Water Data API requests. Defaults to a descriptive identifier including the repo URL.

USGS_REQUEST_TIMEOUT_MSdefault: 30000

HTTP request timeout in milliseconds for each USGS Water Data API request. Every tool call also has a shared 45-second deadline across its requests and retries. Default: 30000.

USGS_API_KEYsecret

Optional api.data.gov key for the USGS Water Data APIs, sent as the X-Api-Key header. Without one, requests share the anonymous per-IP hourly limit (1,000 requests on the OGC collections); a shared or hosted deployment should set one.

WATER_DATAFRAME_DROP_ENABLEDdefault: false

Set to true to make water_dataframe_drop callable — it removes one staged table from a DataCanvas. Off by default, which lists the tool as disabled. Needs CANVAS_PROVIDER_TYPE=duckdb to have anything to drop.

MCP_LOG_LEVELdefault: info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault: http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault: 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault: 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault: /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault: none

Authentication mode to use: 'none', 'jwt', or 'oauth'.