mcp-server-usgs-nationalmap

An MCP (Model Context Protocol) server that wraps the USGS NHDPlus High Resolution (NHDPlus HR) ArcGIS REST MapServer, letting an LLM query official U.S. hydrography — streams, rivers, lakes, stream gages, water features, and watershed boundaries — for a point or arbitrary GeoJSON geometry.

• Service: https://hydro.nationalmap.gov/arcgis/rest/services/NHDPlus_HR/MapServer

• Source: USGS — National Hydrography Dataset Plus High Resolution

• Auth: none (public service)

• Package: hydro_mcp

What the dataset is

NHDPlus HR is a nationally seamless, routed hydrography network built from the high-resolution NHD, the Watershed Boundary Dataset (WBD), and 3DEP elevation. The MapServer exposes 13 layers; this server wraps the ones most useful for site/hydrology analysis.

Related MCP server: geocontext

Tools

All geometry tools accept either a lat + lon pair (convenience) or a GeoJSON geometry string. Supported GeoJSON types: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, plus a BoundingBox shorthand {"type": "BoundingBox", "bbox": [minLon, minLat, maxLon, maxLat]}. All coordinates are WGS84 decimal degrees. Feature geometry is not returned (payloads stay small); results include provenance.

Conventions & gotchas

• Coordinates: WGS84 lat/lon. Convert addresses/place names to coordinates first.

• Point/line layers (gages, water features): pass a Polygon or BoundingBox to capture nearby features — a bare point rarely coincides exactly with a point/line feature.

• Feature codes: ftype/fcode are integers; results add ftype_label / fcode_label (e.g. 46006 → "Stream/River: Perennial"). hutype and purpcode are similarly labeled.

• Drainage-area units differ: gages report dasqmi in square miles; flowlines/watersheds use AreaSqKm / TotalDrainageAreaSqKm.

• Pagination: each layer caps at 2000 records/request; results paginate automatically and set truncated: true if a cap is hit.

• Field names on the service are lowercase; the CamelCase forms are aliases.

Setup

uv sync

Run

# stdio (Claude Desktop, Claude Code, local MCP clients)
uv run python -m hydro_mcp.app

# HTTP (set PORT or DATABRICKS_APP_PORT); served at /mcp, health at /health
PORT=8000 uv run python -m hydro_mcp.app

Project structure

src/hydro_mcp/
├── app.py            # FastMCP init, instructions, transport wiring
├── routes.py         # /health endpoint
├── models.py         # constants, layer IDs, curated field lists, code label maps, dataclasses
├── utils.py          # ArcGIS HTTP client (stdlib urllib), GeoJSON->Esri, code translation
└── tools/            # one file per tool
    ├── __init__.py           # register_tools(mcp)
    ├── find_waterways.py
    ├── find_waterbodies.py
    ├── find_gages.py
    ├── find_water_features.py
    ├── identify_watershed.py
    ├── count_features.py
    └── list_layers.py

Possible future add-ons

The current tools are geometry-intersection queries. NHDPlus HR is a fully routed network, which opens up several higher-value tools not yet implemented:

• Upstream/downstream network tracing (hydro_trace_upstream / hydro_trace_downstream): walk the flowline network from a starting reach using hydroseq, levelpathi, uphydroseq/dnhydroseq, and fromnode/tonode. Enables "what's upstream of this point?" and pollutant/ flow-path questions.

• Watershed routing traversal: follow tohuc from a starting HUC12 down the drainage chain (or accumulate the upstream set) to build drainage lineages.

• Catchment lookup (NHDPlusCatchment, layer 10): return the elevation-based incremental catchment polygon(s) for a location, and join to flowline VAAs via nhdplusid.

• Reach-code / NHDPlusID lookup tools: fetch a specific reach or feature by reachcode / permanent_identifier / nhdplusid rather than by geometry.

• Gage cross-walk to NWIS: resolve sourceid/gageidma to live USGS NWIS streamflow observations.

• Attribute filtering: expose a where filter (e.g. minimum stream order, perennial-only) on the find_* tools for large-area queries.

Data source & attribution

USGS The National Map — National Hydrography Dataset Plus High Resolution (NHDPlus HR). Public domain. See https://www.usgs.gov/national-hydrography/national-hydrography-dataset.