usgs-mcp

MCP server providing access to USGS Water Services for real-time streamflow, flood stages, peak events, and historical statistics.

This server fills a critical gap in the ocean-mcp ecosystem by providing inland flooding and river data — often the deadliest aspect of hurricanes and storms.

Data Sources

• USGS Water Services (waterservices.usgs.gov) — real-time and historical streamflow data
• USGS NWIS Peak (nwis.waterdata.usgs.gov) — annual peak streamflow records

No API key required. All data is public domain.

Tools (10)

Site Discovery

Streamflow Data

Flood Analysis

Statistics

Quick Start

Install from PyPI

uvx usgs-mcp

Install from source

cd servers/usgs-mcp
uv sync
uv run usgs-mcp

Claude Desktop Configuration

{
  "mcpServers": {
    "usgs": {
      "command": "uvx",
      "args": ["usgs-mcp"]
    }
  }
}

Example Queries

• "What is the current streamflow on the Potomac River?" → usgs_get_instantaneous_values(site_number="01646500")
• "Find USGS gauges in Texas" → usgs_find_sites(state_code="TX")
• "Is the Mississippi at St. Louis flooding?" → usgs_get_flood_status(site_number="07010000")
• "What were the biggest floods on the Potomac?" → usgs_get_peak_streamflow(site_number="01646500")

Development

cd servers/usgs-mcp
uv sync --group dev

# Unit tests (no network)
uv run pytest tests/ --ignore=tests/test_live.py --ignore=tests/test_mcp_protocol.py -v

# Integration tests (needs network)
uv run pytest tests/test_live.py -v

# MCP protocol test
uv run pytest tests/test_mcp_protocol.py -v

License

MIT