# io.github.andrewschristison/pondlog-usgs (npm · @pondlog/mcp-usgs)

USGS Water Services MCP server. Real-time streamflow, gage height, and site metadata from NWIS.

- Trust score: 68/100 (medium)
- Change this week: +25
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `@pondlog/mcp-usgs`: 68/100 (this document), [markdown](https://verifymcp.io/servers/andrewschristison-pondlog-usgs/pondlog-mcp-usgs.md), [page](https://verifymcp.io/servers/andrewschristison-pondlog-usgs/pondlog-mcp-usgs)

## Channel facts

- Registry: `npm`
- Package: `@pondlog/mcp-usgs`
- Version: `0.1.6`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (97 of 101), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (97 of 101), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 82 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 69/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 1003 tokens (~250/item across 4 items; 4 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add andrewschristison-pondlog-usgs -- npx -y @pondlog/mcp-usgs
```

### Codex

```bash
codex mcp add andrewschristison-pondlog-usgs -- npx -y @pondlog/mcp-usgs
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "andrewschristison-pondlog-usgs": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@pondlog/mcp-usgs"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add andrewschristison-pondlog-usgs --command npx --arg -y --arg @pondlog/mcp-usgs
```

### Hermes

```yaml
mcp_servers:
  andrewschristison-pondlog-usgs:
    command: "npx"
    args: ["-y", "@pondlog/mcp-usgs"]
```

### Other

```json
{
  "mcpServers": {
    "andrewschristison-pondlog-usgs": {
      "command": "npx",
      "args": [
        "-y",
        "@pondlog/mcp-usgs"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-02 (score 67, +49)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Stability: unverified → 0.23
- [functional] Licence: MIT

### 2026-08-01 (score 18, −7)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 25, +1)

- [security regression] Malware scan: pass → unverified
- [functional improvement] Tool coverage: unverified → 100

### 2026-07-30 (score 24, −19)

- [functional regression] Tool coverage: 100 → unverified
- [functional] First check of Schema quality: unverified

### 2026-07-27 (score 43)

First indexed and scored.

## MCP tools (4)

### `get_instantaneous_values` (~241 tokens)

Real-Time USGS Streamflow / Gage Height

Real-time readings (typically 15-minute cadence) from a USGS gauge. Returns one or more time series, by default discharge (00060, ft³/s) and gage height (00065, ft), over a relative period ending now. Use this to answer 'what is the river doing right now?'. USGS rejects historic dates on this endpoint; for past data use `get_daily_values` with start_date/end_date instead. For a 'what gauges exist near here?' first-step query use `search_sites`.

Input parameters:

- `parameter_codes` (array): Specific 5-digit parameter codes to retrieve. Defaults to ['00060', '00065'] (discharge + gage height). Pass ['00010'] for water temperature, etc.
- `period` (string): Relative time window ending now. Default 'PT2H' (past 2 hours, returns ~8 readings at 15-minute cadence). 'P1D' returns ~96 readings.
- `sites` (array, required): Array of USGS site numbers to fetch in one call. Most queries pass a single site, but the API supports batched fetches.

### `get_daily_values` (~278 tokens)

Daily USGS Streamflow Statistics (Current or Historic)

Daily statistics (default: mean) for one or more USGS gauges. Use this for any query that crosses days or asks about historic dates. Pass either `period` (relative-to-now) OR `start_date`/`end_date` (historic range), not both. For real-time sub-hour resolution prefer `get_instantaneous_values`. Returns one daily value per (site × parameter × statistic × day). USGS quality codes: 'A' = approved, 'P' = provisional.

Input parameters:

- `end_date`: Historic range end (YYYY-MM-DD). Defaults to today when start_date is set.
- `parameter_codes` (array): 5-digit parameter codes. Defaults to ['00060'] (discharge mean).
- `period` (string): Relative window ending now. Examples: 'P7D', 'P30D', 'P1Y'. Mutually exclusive with start_date/end_date.
- `sites` (array, required): Array of USGS site numbers. Single-site queries are typical.
- `start_date` (string): Historic range start (YYYY-MM-DD). Pair with end_date for an explicit window.
- `statistic_codes` (array): USGS statistic codes, '00003' = mean (default), '00001' = max, '00002' = min, '00008' = median.

### `get_site_info` (~150 tokens)

USGS Gauge Site Metadata

Returns metadata for a single USGS gauging station: official name, coordinates, site type (stream/lake/groundwater/etc.), hydrologic unit (HUC), state/county codes, and gauge altitude. Use after `search_sites` finds candidate gauges, or to confirm a site number returned in someone's data.

Input parameters:

- `site_number` (string, required): USGS site number, 8 to 15 digits identifying a single gauging station. Examples: '12045500' (Elwha River at McDonald Bridge near Port Angeles, WA); '12048000' (Dungeness River near Sequim, WA). Use `…

### `search_sites` (~334 tokens)

Find USGS Gauge Sites Near a Location

Find active USGS stream-gauge sites by either (a) latitude/longitude/radius_km, or (b) US state postal code. Returns site numbers, names, coordinates, HUC, and altitude, feed the resulting site numbers into `get_instantaneous_values` or `get_daily_values`. Defaults filter to surface-water streams (siteType=ST) with real-time data (hasDataTypeCd=iv); pass site_type/has_data_type to override. Pass either lat+lng+radius_km OR state_code; the lat/lng path is preferred for place-aware queries.

Input parameters:

- `has_data_type` (string): Restrict to sites that publish the given data type: 'iv' = instantaneous (real-time, default), 'dv' = daily values, 'qw' = water quality, 'gw' = groundwater levels.
- `lat` (number): Latitude of the search center. Required if state_code is not provided.
- `lng` (number): Longitude of the search center. Required if state_code is not provided.
- `radius_km` (number): Search radius in km around (lat, lng). Default 25.
- `site_type` (string): USGS site type code: 'ST' = stream (default), 'LK' = lake, 'GW' = groundwater, 'AT' = atmosphere, 'ES' = estuary. Full list: https://help.waterdata.usgs.gov/site_tp_cd
- `state_code` (string): US two-letter state code. Mutually exclusive with lat/lng. Returns ALL active stream gauges in the state.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/andrewschristison-pondlog-usgs/pondlog-mcp-usgs#diagnostics

## Score history

- 2026-08-03: 68
- 2026-08-02: 67
- 2026-08-01: 18
- 2026-07-31: 25
- 2026-07-30: 24
- 2026-07-28: 43
- 2026-07-27: 43

## Links

- npm package: https://www.npmjs.com/package/@pondlog/mcp-usgs
- Socket report: https://socket.dev/npm/package/@pondlog/mcp-usgs
- Repository: https://github.com/andrewschristison/pondlog
- Changelog RSS feed: https://verifymcp.io/servers/andrewschristison-pondlog-usgs/pondlog-mcp-usgs/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/andrewschristison-pondlog-usgs/pondlog-mcp-usgs/changelog.json
- HTML version of this page: https://verifymcp.io/servers/andrewschristison-pondlog-usgs/pondlog-mcp-usgs