USGS Water MCP
Overview
This MCP server provides comprehensive access to USGS water data through three APIs:
- USGS Water Services API - Real-time water measurements (stream flow, gage height, temperature, etc.)
- Real-Time Flood Impacts API - Current flooding conditions and reference points
- OGC API - Monitoring location metadata, agency codes, and geological information
The server is modularly designed with separate API handlers unified through a single entry point.
Project Structure
Service
If you want a clean web interface that utilizes these tools visit https://aqua-node.onrender.com/landing and help me do some testing!
Sample Output
Here's an example of fetching stream flow data for the Potomac River:
Installation
Installing via pip
Manual Installation
- Clone this repository
- Install dependencies:
Connecting with Claude Desktop
- Edit your Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%/Claude/claude_desktop_config.json
- macOS:
- Add the server configuration:
- Restart Claude Desktop
Available Tools
Water Data Tools
fetch_usgs_data
Fetch instantaneous water data from USGS monitoring stations.
Parameters:
sites
(required): Comma-separated site numbers (e.g., "01646500" or "01646500,01647000")parameter_codes
(optional): Comma-separated parameter codes (e.g., "00060,00065")start_date
(optional): Start date in ISO format (YYYY-MM-DD or YYYY-MM-DDTHH)end_date
(optional): End date in ISO formatperiod
(optional): Period code (e.g., "P7D" for 7 days)
Common Parameter Codes:
00060
: Discharge (stream flow)00065
: Gage height00010
: Temperature, water00300
: Dissolved oxygen00400
: pH
Example Usage:
Real-Time Flood Impact Tools
get_flooding_reference_points
Get currently flooding reference points (updated every 30 minutes).
get_reference_points
Get paginated list of reference points.
Parameters:
page
(optional): Page number (default: 1)limit
(optional): Number of results per page (default: 100)
get_reference_point_by_id
Get specific reference point by ID.
Parameters:
reference_point_id
(required): The reference point ID
get_reference_points_by_state
Get reference points for a specific state.
Parameters:
state_id
(required): State ID (e.g., "CA", "TX")
get_reference_point_by_nwis_id
Get reference point by USGS gage ID.
Parameters:
nwis_id
(required): USGS National Water Information System site ID
get_reference_points_by_nws_id
Get reference points by National Weather Service ID.
Parameters:
nws_id
(required): National Weather Service location ID
get_inactive_reference_points
Get inactive reference points.
get_states
Get list of states.
get_state_by_id
Get specific state information.
Parameters:
state_id
(required): State ID (e.g., "CA", "TX")
get_counties
Get list of counties.
get_counties_by_state
Get counties for a specific state.
Parameters:
state_id
(required): State ID (e.g., "CA", "TX")
get_nws_usgs_crosswalk
Get NWS/USGS crosswalk data.
OGC API Tools
get_monitoring_locations
Get monitoring locations with extensive filtering options.
Parameters:
bbox
(optional): Bounding box as "minx,miny,maxx,maxy"limit
(optional): Maximum number of results (default: 100)offset
(optional): Starting offset for pagination (default: 0)agency_code
(optional): Filter by agency code (e.g., "USGS")state_code
(optional): Filter by state code (e.g., "CA")county_code
(optional): Filter by county codesite_type_code
(optional): Filter by site type codemonitoring_location_number
(optional): Specific monitoring location number
get_monitoring_location_by_id
Get specific monitoring location by ID.
Parameters:
location_id
(required): The monitoring location ID
get_agency_codes
Get agency identification codes.
Parameters:
limit
(optional): Maximum number of results (default: 100)offset
(optional): Starting offset for pagination (default: 0)
get_altitude_datums
Get vertical datum information (recommended: NAVD88).
Parameters:
limit
(optional): Maximum number of results (default: 100)offset
(optional): Starting offset for pagination (default: 0)
get_aquifer_codes
Get aquifer identification information.
Parameters:
limit
(optional): Maximum number of results (default: 100)offset
(optional): Starting offset for pagination (default: 0)
get_aquifer_types
Get aquifer type information (confined vs unconfined).
Parameters:
limit
(optional): Maximum number of results (default: 100)offset
(optional): Starting offset for pagination (default: 0)
get_coordinate_accuracy_codes
Get coordinate accuracy codes for latitude-longitude values.
Parameters:
limit
(optional): Maximum number of results (default: 100)offset
(optional): Starting offset for pagination (default: 0)
Troubleshooting
Common Issues
- API Connection Errors: Ensure you have an active internet connection and the USGS API is accessible
- Invalid Site Numbers: Verify site numbers exist using the USGS Water Data for the Nation website
- No Data Available: Some sites may not have data for the requested time period or parameters
- Rate Limiting: The USGS API has usage limits; avoid making too many requests in quick succession
Finding Site Numbers
Use the USGS Water Data for the Nation website to find monitoring station site numbers in your area of interest.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Provides access to real-time water data from the USGS Water Services API, allowing users to fetch instantaneous measurements like stream flow, gage height, temperature, and water quality parameters from thousands of monitoring stations across the US.
Related MCP Servers
- AsecurityAlicenseAqualityProvides real-time information about U.S. National Parks through the NPS API, enabling users to search parks, check details, alerts, visitor centers, campgrounds, and upcoming events.Last updated -63,04120TypeScriptMIT License
- -securityAlicense-qualityReal-time hydrological information retrieval service that provides water level, precipitation, dam discharge data, and observatory location information.Last updated -1PythonApache 2.0
- AsecurityAlicenseAqualityThis server provides tools for interacting with the NOAA Tides and Currents API, enabling access to water level data, tide predictions, currents data, station information, and astronomical information like moon phases and sun times.Last updated -15133TypeScriptMIT License
- -securityFlicense-qualityProvides weather forecast and alert data for US locations through the National Weather Service API, enabling access to real-time weather alerts by state and detailed forecasts by coordinates.Last updated -JavaScript