Watershed MCP Server

Live watershed data as MCP tools, built for owockibot.xyz bounty #477 ($10 USDC). Exposes river queries, USGS gauge readings, and EPA compliance rankings.

What it does

Five tools over the stdio MCP transport:

All data sources are public and require no API keys. The vendored #450 schema lives in schema/ecological-sensor-reading.schema.json (original: xtratrezzy/ecological-sensor-schema, submitted for bounty #450).

Related MCP server: mcp-usgs-water-data

Setup

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Run

Stdio (for Claude Desktop / MCP clients):

python -m watershed_mcp.server

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "watershed": {
      "command": "/path/to/repo/.venv/bin/python",
      "args": ["-m", "watershed_mcp.server"],
      "cwd": "/path/to/repo"
    }
  }
}

Example session

> search_rivers("Colorado", state="co", limit=3)
{"count": 3, "sites": [{"site_no": "09163500", "station_name": "COLORADO RIVER NEAR COLORADO-UTAH STATE LINE", ...}]}

> get_gauge_readings("09163500")
{"site": {...}, "schema_ref": "https://github.com/xtratrezzy/ecological-sensor-schema/...",
 "readings": [
   {"schema_version": "1.0.0", "sensor_id": "USGS:09163500:00010", "sensor_type": "water_quality",
    "parameter": "temperature", "value": 17.8, "unit": "celsius",
    "timestamp": "2026-09-29T00:45:00.000-06:00",
    "location": {"lat": 39.0, "lng": -109.05},
    "source": "USGS NWIS Water Services via owockibot bounty #477 watershed MCP server",
    "quality_flag": "raw", ...},
   ... ]}

> epa_compliance_ranking(38.9, -77.03, radius_miles=20)
{"facilities": 3342, "violations_last_4_quarters": 175, "compliance_score": 94.8, "grade": "A", ...}

Tests

python tests/test_server.py

The test harness spawns the server over real stdio MCP, runs initialize / tools/list / tools/call against live USGS and EPA endpoints, and validates every gauge reading against the vendored #450 schema with jsonschema.Draft202012Validator.

Submission / deploy notes (for the claimer)

1. Create a public GitHub repo (e.g. watershed-mcp), push this directory.

2. Zip the repo (excluding .venv/) and upload to Arweave (e.g. via ardrive or arweave CLI) — the bounty asks for an Arweave-hosted build.

3. Claim bounty #477 on owockibot.xyz with the GitHub repo URL + Arweave link in the submission. Note the proposer-priority window: only wallet 0xbc97e858bec05ba05be1e3bd63f65d3cbbecc4 may claim until 2026-09-29T20:03:00Z; claims open to everyone after that.

License

MIT