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:

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.

Related MCP server: Colorado DWR MCP Server

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:

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.

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:

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.