USGS Water

You set up this MCP server to access USGS water data through three APIs: real-time water measurements, real-time flood reference points, and geographic metadata. It aggregates these capabilities behind a single entry point so your MCP client can request diverse water information from one place.

How to use

Connect your MCP client to the configured MCP server entry point you run locally. You will load the local server as a stdio process and then issue data requests through your MCP client interface. Use the server name you configured (for example usgs_water) to route specific data requests. Your MCP client can request water measurements, flood reference points, and OGC location metadata by selecting the appropriate tool or endpoint exposed by the MCP server. The server handles the three APIs behind a unified entry point, so you can query streamflow, gage height, temperature, current flood reference points, and monitoring locations in a consistent way.

Typical usage patterns include requesting instantaneous water data for one or more USGS sites, obtaining current flood reference points, and retrieving monitoring location metadata. You won’t need to manage separate connections to multiple services because the server consolidates them into a single MCP interface.

How to install

Prerequisites: ensure you have Python installed on your system. Use Python 3.x and a functioning environment where you can run the MCP server as a local process.

Create a small MCP configuration that points to the local Python runtime and your server entry script. Use the following example as a starting point and adjust the path to your actual main script.

{
  "mcpServers": {
    "usgs_water": {
      "command": "python",
      "args": ["/path/to/usgs-water-mcp/main.py"]
    }
  }
}

Run the MCP server using the command shown in your configuration. The exact command will come from your MCP client configuration; the example above demonstrates starting the local stdio server via Python.

Additional information and notes

The MCP server provides three APIs: USGS Water Services API for real-time measurements, Real-Time Flood Impacts API for current flooding conditions, and the OGC API for monitoring location metadata. It is designed so you can access all three through a single entry point.

Troubleshooting

If you encounter issues connecting to the MCP server, verify your local Python runtime is available and that the main script path in your configuration is correct. Ensure your MCP client is configured to target the server name you defined (for example usgs_water) and that the stdio process has permission to run. If you see missing data for a given site, confirm the site number exists in USGS data and that the requested parameters are supported.

Security and maintenance

Keep your Python environment updated and use a minimal, trusted environment to run the MCP server. Do not expose the local MCP process to untrusted networks without appropriate access controls.

Available tools

fetch_usgs_data

Fetch instantaneous water data from USGS monitoring stations for specified sites and parameters across optional date ranges.

get_flooding_reference_points

Retrieve currently flooding reference points updated periodically to reflect real-time flood conditions.

get_reference_points

Get a paginated list of flood reference points with optional filtering by page and limit.

get_reference_point_by_id

Fetch a single reference point using its unique reference_point_id.

get_reference_points_by_state

Obtain reference points for a specific state identified by state code.

get_reference_point_by_nwis_id

Find a reference point by its USGS NWIS site ID.

get_reference_points_by_nws_id

Find a reference point by its National Weather Service location ID.

get_inactive_reference_points

List reference points that are currently inactive.

get_states

Provide a list of states for which reference points are available.

get_state_by_id

Get detailed information for a specific state by its ID.

get_counties

Return a list of counties that have reference points.

get_counties_by_state

Get counties within a specific state.

get_nws_usgs_crosswalk

Access crosswalk data between NWS and USGS identifiers.

get_monitoring_locations

Retrieve monitoring locations with extensive filtering such as bbox, agency code, state, and site type.

get_monitoring_location_by_id

Fetch a single monitoring location by its ID.

get_agency_codes

List agency codes used to classify monitoring locations.

get_altitude_datums

Provide vertical datum information like NAVD88 for measurements.

get_aquifer_codes

Return aquifer identification information.

get_aquifer_types

Describe aquifer types such as confined or unconfined.

get_coordinate_accuracy_codes

Offer codes describing coordinate precision for locations.