Skip to main content
Glama
mcp-server-usace-iwr

mcp-server-usace-iwr

by GSA-TTS

mcp-server-usace-iwr

An MCP (Model Context Protocol) server that wraps the U.S. Army Corps of Engineers (USACE) Institute for Water Resources (IWR) River Mile Marker ArcGIS Feature Service, letting an LLM locate river mile markers on navigable U.S. rivers and answer "what river mile am I at?" style questions.

  • Dataset: USACE River Mile Markers

  • Service: https://services7.arcgis.com/n1YM8pTrFmm7L4hs/arcgis/rest/services/usace_river_mile_markers/FeatureServer/0

  • Auth: none (public service)

  • CRS: WGS84 (EPSG:4326) decimal degrees

Tools

Tool

Purpose

usace_rivermile_nearest

Return the single closest marker to a lat/lon (with distance + bearing).

usace_rivermile_find_markers

Find markers near a point (radius) or within a GeoJSON geometry/bbox.

usace_rivermile_query

Filter markers by river name and/or mile-value range, with pagination.

All tools are read-only and return provenance (source agency, dataset, service URL, layer, CRS, retrieval time).

Related MCP server: pumperly-mcp

Layer fields

name, LONGITUDE1, LATITUDE1, MILE, RIVER_CODE, RIVER_NAME, RIVER_NUMB, SOURCE.

Running locally (stdio)

uv sync
uv run python -m usace_iwr_server.app

The server uses stdio transport by default. If a PORT (or DATABRICKS_APP_PORT) environment variable is set, it serves streamable HTTP at /mcp instead, with a /health readiness endpoint.

Container / deployment

bash scripts/build-and-push.sh   # builds linux/amd64 and pushes to GHCR

Development

uv run python -m py_compile src/usace_iwr_server/*.py src/usace_iwr_server/tools/*.py
npx @modelcontextprotocol/inspector uv run python -m usace_iwr_server.app

Available Tools

3 tools
usace_rivermile_find_markersFind River Mile Markers Near a LocationA
Read-onlyIdempotent

Find USACE river mile markers near a point or within a geometry.

Accepts EITHER a lat/lon pair (+ radius_meters) OR a GeoJSON geometry string.

Use lat+lon when: "What river mile markers are near 31.45, -92.71?", "Markers within 2 km of this boat ramp?" Use geometry when: "Which markers fall inside this county polygon / bbox?", "Markers along this river-reach corridor?"

For point (lat/lon) queries, each returned marker includes 'distance_m' (great-circle meters from the query point) and results are sorted nearest-first. Geometry queries return markers intersecting the geometry.

Returns: { "count": int, # markers returned (after limit) "truncated": bool, # true if more markers matched than returned "markers": [ { name, MILE, RIVER_NAME, RIVER_CODE, RIVER_NUMB, LONGITUDE1, LATITUDE1, SOURCE, distance_m? }, ... ], "query": { "type": str, "radius_meters": float|null, "crs_epsg": int }, "provenance": { source agency, dataset, service URL, layer, CRS, retrieved_utc } }

Error responses:

  • "Error: supply either lat+lon or geometry, not both (or neither)"

  • "Error: 'geometry' is not valid JSON: ..."

  • "Error: unsupported geometry type ..."

  • "Error: River Mile request failed: ..."

Inputs: lat, lon, limit, geometry, +1 more. Returns: object

usace_rivermile_nearestNearest River Mile Marker to a LocationA
Read-onlyIdempotent

Return the single closest river mile marker to a WGS84 coordinate.

Answers "what river mile am I at?" / "nearest marker to this point". Searches within max_radius_meters and returns the nearest marker with its great-circle distance, plus a plain-language finding.

Returns: { "finding": str, # e.g. "Nearest marker: RED River, Mile 111, ~180 m NE" "found": bool, "nearest": { name, MILE, RIVER_NAME, RIVER_CODE, RIVER_NUMB, LONGITUDE1, LATITUDE1, SOURCE, distance_m, bearing } | null, "candidates_searched": int, "query": { "lat": float, "lon": float, "max_radius_meters": float, "crs_epsg": int }, "provenance": { source agency, dataset, service URL, layer, CRS, retrieved_utc } }

Error responses:

  • "Error: River Mile request failed: ..."

Inputs: lat (required), lon (required), max_radius_meters. Returns: object

usace_rivermile_queryQuery River Mile Markers by River and Mile RangeA
Read-onlyIdempotent

Query USACE river mile markers by river name and/or mile-value range.

Use when: "List markers on the RED river", "How many markers on the Mississippi between mile 400 and 600?", "Show markers on the Ohio above mile 900" (mile_min=900).

Results are ordered by MILE ascending and paginated. total_count reflects all matching markers; use next_offset to fetch the next page.

Returns: { "count": int, # markers on this page "total_count": int, # total markers matching the filter "has_more": bool, "next_offset": int|null, # pass as 'offset' to get the next page "where": str, # the WHERE clause applied (for transparency) "markers": [ { name, MILE, RIVER_NAME, RIVER_CODE, RIVER_NUMB, LONGITUDE1, LATITUDE1, SOURCE }, ... ], "provenance": { source agency, dataset, service URL, layer, CRS, retrieved_utc } }

Error responses:

  • "Error: mile_min cannot be greater than mile_max"

  • "Error: provide at least one filter (river_name, mile_min, or mile_max)"

  • "Error: River Mile request failed: ..."

Inputs: limit, offset, mile_max, mile_min, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: find_markers returns all markers near a point or within a geometry, nearest returns the single closest marker to a coordinate, and query filters by river name and mile range. Their descriptions are thorough and include usage guidance that eliminates ambiguity.

    Naming Consistency4/5

    All tool names follow a `usace_rivermile_verb` pattern, using clear and descriptive verbs (find_markers, nearest, query). The naming is consistent and predictable, though slightly long. A minor deviation is that 'nearest' is an adjective rather than a verb, but the intent is still clear.

    Tool Count5/5

    Three tools is an ideal count for this specialized domain. Each tool addresses a distinct and common query pattern for river mile markers: spatial search, nearest point, and attribute-based filtering. There are no redundant or missing core operations.

    Completeness4/5

    The tool set covers the primary use cases for querying river mile markers: proximity search, nearest-marker lookup, and attribute filtering/pagination. A minor gap is the lack of a tool to retrieve a single marker by ID or name, but the existing tools cover the most common workflows without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      An experimental MCP server providing spatial context for LLMs by interfacing with French Geoplateforme services. It enables tasks such as geocoding, altitude lookups, and querying administrative, cadastral, or urban planning data.
      10 npm
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that gives AI assistants direct access to the FEMA National Flood Hazard Layer (NFHL) for flood zone lookups, FIRM panel information, and flood map data in the United States.
      6
      27 npm
      MIT