mcp-usgs-water-data

An MCP server that exposes the USGS Instantaneous Values (IV) web service as tools — real-time and historical streamflow, gage height, water temperature, and related measurements from USGS gauges across the United States.

It is built for a language model to use safely. The USGS API is designed for browsers and bulk downloads; feeding its responses straight to a model goes wrong in ways that are easy to miss and hard to notice — a state-wide query returns megabytes of JSON, a "latest value" can be seven years old, and a river with no gauge returns an empty result the model will invent a reason for. This server exists to turn those traps into structured, self-describing answers.

What it does

Three tools:

Tool	Purpose
find_sites	Resolve a place or river name to USGS station numbers. Start here when you know the river but not its 8- or 15-digit site number.
get_instantaneous_values	Fetch readings for one or more sites. The main tool.
list_common_parameter_codes	Look up the 5-digit USGS code for a measurement (e.g. streamflow = 00060). No network call.

The usual flow is find_sites → get_instantaneous_values. A model asking "what's the flow of the Chattahoochee in Atlanta?" resolves the name to site 02336000, then reads it.

Requirements

• Node.js 22+ (uses native fetch with transparent gzip; no HTTP dependencies).

Install

npm install
npm run build   # compiles TypeScript to dist/
npm test        # 189 tests, no network access required

Configure your MCP client

The server speaks MCP over stdio. Point your client at the built entry file.

Claude Code (project-scoped, committable):

claude mcp add usgs-water --scope project -- node /absolute/path/to/dist/src/index.js

This writes .mcp.json. Project-scoped servers are never auto-trusted — restart claude in the project directory and approve the server once when prompted.

Any MCP client, directly:

{
  "mcpServers": {
    "usgs-water": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/dist/src/index.js"]
    }
  }
}

The config runs dist/, not the TypeScript source. Run npm run build after any code change, or the server will keep running the old build.

Tools

get_instantaneous_values

Exactly one major filter is required to scope the query — providing zero or more than one is rejected before any network call:

Filter	Type	Notes
sites	string[]	Station numbers, e.g. ["01646500"]. Up to 100. Not river names — use find_sites.
stateCd	string	Two-letter state code, e.g. "NY".
countyCd	string[]	5-digit FIPS codes, e.g. ["24031"]. Up to 20.
huc	string[]	Hydrologic Unit Codes: one 2-digit region, or up to ten 8-digit sub-basins.
bBox	object	{ west, south, east, north } in decimal degrees. Longitudes are negative in the US. Area capped at 25 square degrees.

Optional narrowing: parameterCd (which measurements), siteType, siteStatus, modifiedSince, agencyCd.

Time window — pick one, they are mutually exclusive:

• (none) — the single latest value per sensor.
• period — an ISO-8601 duration ending now, e.g. "P7D" (last 7 days), "PT6H" (last 6 hours).
• startDT / endDT — an absolute range, e.g. "2024-01-01" or "2024-01-01T12:00". endDT requires startDT. Data begins 2007-10-01.

Output:

• mode — "values" (default; individual readings) or "summary" (count, min, max, mean, first, last). Use "summary" for any window longer than a day — a single site over one year is ~35,000 readings.
• maxValues — cap on readings per series in "values" mode (default 200, max 1000).

find_sites

Same one-major-filter rule (sites / stateCd / countyCd / huc / bBox), plus:

• nameContains — case-insensitive substring match on the station name. Applied client-side after fetching by the major filter, so it narrows the results, not the request. A stateCd query can return hundreds of sites before filtering.
• siteType, siteStatus (default "active"), hasDataTypeCd (default "iv" — only sites that report instantaneous values), maxSites (default 50, max 500).

list_common_parameter_codes

No input. Returns the table below.

Code	Measurement	Unit
00060	Discharge (streamflow)	ft³/s
00065	Gage height	ft
00010	Water temperature	°C
00095	Specific conductance	µS/cm @25°C
00300	Dissolved oxygen	mg/L
00400	pH	std units
63680	Turbidity	FNU
00045	Precipitation	in
72019	Depth to water level	ft
62614	Lake/reservoir elevation (NGVD 1929)	ft
62615	Lake/reservoir elevation (NAVD 1988)	ft
00020	Air temperature	°C
00025	Barometric pressure	mm Hg
00035	Wind speed	mph
00036	Wind direction	degrees
00052	Relative humidity	%
00055	Stream velocity (point)	ft/s

Reading the output

The response has a top-level series array. Each series carries the site, the variable, the sensor method, qualifier codes, and either readings or a summary. A few fields exist specifically to prevent a confidently wrong answer, and a consumer should check them.

On each series:

• stale (true / false / null) — true means the latest reading is more than 48 hours behind the query's reference time. USGS returns decommissioned sensors in a latest-value query, frozen at their final reading — a temperature sensor switched off in 2019 will otherwise look current. null means staleness could not be evaluated. Check this before reporting any value as current.
• discontinued — the sensor is marked decommissioned in its metadata. A hint that explains why a series is stale; not itself a freshness signal.
• truncated / totalValues — set when maxValues capped a series. You are seeing the most recent N, not the whole record.
• qualifiers — most recent USGS data is provisional (code P) and subject to revision. These are never stripped.

On the response (not the series):

• missingParameterCodes — present when you requested a parameterCd a site does not measure. Series are not positionally aligned with the codes you asked for; match on each series' variable.code.
• note — a plain-language explanation attached to empty results, stale series, or dropped parameters, so an empty or partial answer is never silently ambiguous.

When a response would exceed 256 KB even after shaping, the server returns an error naming summary mode rather than truncating silently.

Rate limiting

USGS publishes no numeric rate limit but blocks IP addresses it judges to be "seriously impacting others." A single client session can fan out — subagents issuing many concurrent tool calls all route through this one server process on one IP — so the server gates its own outbound traffic: a shared limiter with a concurrency cap, minimum spacing between requests, and a load-shedding valve that returns a "retry shortly" error rather than hanging when a burst overwhelms it. There is deliberately no retry-on-failure loop — retrying into a throttling server is how you earn the block.

Three environment variables, read once at startup:

Variable	Default	Meaning
USGS_MAX_CONCURRENCY	4	Requests in flight at once.
USGS_MIN_INTERVAL_MS	75	Minimum gap between request starts (~13/s ceiling).
USGS_MAX_QUEUE_WAIT_MS	45000	Shed a request that would wait longer than this.

Tune concurrency and spacing up for a purely interactive deployment, down for a scheduled batch collector. Negative and non-numeric values fall back to the default. Zero falls back for concurrency and queue-wait (both are degenerate at 0 — a zero concurrency cap deadlocks, a zero queue-wait sheds every request), but 0 is a valid "no added spacing" setting for the interval.

The upstream base URLs are not currently configurable; they are constants in src/usgs.ts and src/sites.ts.

Scope and limits

• No site lookup by coordinates-you-assert. find_sites resolves names and geographic filters; a bounding box you get wrong will still return an honest (possibly empty) result.
• Groundwater-only filters (aquifer codes, well/hole depth) are not exposed. Additive if needed.
• 503 is not retried. The gate prevents the burst that causes throttling; it does not retry after one occurs.
• One documented staleness corner: a future endDT combined with a payload missing its request timestamp marks live data as stale. Unobserved in practice, errs toward caution.

Design rationale for every one of these decisions — and the live-service behavior that drove them — is in DESIGN.md.

Development

npm run build   # tsc -> dist/
npm test        # build, then node --test (no network)

Tests are deterministic and hermetic: no live network calls, no wall-clock or timezone dependence (the suite passes identically under any TZ). Fixtures under test/fixtures/ are real captured USGS responses, not synthesized.

License

MIT. USGS water data is in the public domain; this license covers the server code only.