# USGS Water Services MCP

> USGS Water Services MCP Server gives you direct access to real-time and historical water data from the US Geological Survey. You can pull streamflow, groundwater levels, and site metadata across the entire country using simple prompts. Need to know how high a river was last week or where a specific monitoring station is located? This server handles it all: instant readings, daily averages, specialized aquifer tracking, and full site searches.

## Overview
- **Category:** industry-titans
- **Price:** Free
- **Tags:** hydrology, environmental-data, water-monitoring, real-time-data, geospatial-data, climate-science

## Description

The USGS Water Services MCP gives your AI client direct access to real-time and historical water data from the US Geological Survey. You can pull streamflow, groundwater levels, and site metadata across the entire country using simple prompts. This server handles instant readings, daily averages, specialized aquifer tracking, and full site searches for monitoring stations.

To start, you'll use `get_sites` to search and grab all the metadata about specific USGS monitoring locations. You can narrow down your search fast by filtering for sites based on state, county, or HUC codes, letting you pinpoint exactly where you need data from. Once you have a site ID, you can check what kind of water measurements they collect.

If you need to know what's happening right now—or close enough—you use `get_instantaneous_values`. This tool pulls near real-time water data, typically at 15-minute intervals, based on a site location filter. It gives you current streamflow and water levels as they fluctuate minute by minute.

To see how things changed over the last few days or weeks, call `get_daily_values`. This retrieves historical daily summaries for flow rates and water levels, providing you with the mean, median, max, and min values for a given period. You're not just getting one number; you're getting a full picture of the day’s range.

For deeper statistical analysis over longer stretches, you use `get_statistics`. This tool generates aggregated reports—whether it's daily averages, monthly totals, or annual measurements—based on approved hydrological data sets. You can calculate macro-level trends without having to crunch massive spreadsheets yourself.

If your interest lies in subsurface water, you need the specialized function `get_groundwater_levels`. This tool pulls historical readings specifically for manually-recorded groundwater levels within an aquifer system. It doesn't deal with surface river flow; it tracks what's underground. You use this when you gotta know about the depth of the water table.

You don't have to jump between tools either. The server lets your agent manage all these data streams—from finding a specific station using `get_sites`, getting its current 15-minute reading via `get_instantaneous_values`, tracking that day’s min/max flow with `get_daily_values`, compiling annual stats through `get_statistics`, or pulling back years of deep aquifer data using `get_groundwater_levels`—all within your chat window.

## Tools

### get_daily_values
Retrieves historical daily summaries (mean, median, max, min) of water data.

### get_groundwater_levels
Pulls historical readings for manually-recorded groundwater levels in an aquifer.

### get_instantaneous_values
Gets near real-time water data, usually at 15-minute intervals, based on site location filters.

### get_sites
Searches for and retrieves metadata about specific USGS monitoring locations.

### get_statistics
Generates aggregated daily, monthly, or annual statistical reports on hydrological measurements.

## Prompt Examples

**Prompt:** 
```
Search for all active USGS water monitoring sites in Florida.
```

**Response:** 
```
I've found several active sites in Florida. For example, site 02236000 (ST. JOHNS RIVER NEAR COCOA, FL) and site 02248000 (ST. JOHNS RIVER NEAR DE LAND, FL). Would you like to see the full list or details for a specific one?
```

**Prompt:** 
```
Get the last 7 days of water level data for site 08313000.
```

**Response:** 
```
Retrieving data for site 08313000 (RIO GRANDE AT OTOWI BRIDGE, NM)... Over the last 7 days, the gage height has fluctuated between 3.12 and 3.45 feet. Would you like a more detailed breakdown of the 15-minute intervals?
```

**Prompt:** 
```
What are the daily mean statistics for discharge at site 01646500?
```

**Response:** 
```
For site 01646500 (POTOMAC RIVER NEAR WASH, DC), the daily mean discharge for today's date historically is 12,400 cubic feet per second (cfs). The record high for this day was 85,000 cfs in 1996.
```

## Capabilities

### Find Monitoring Stations
Search and retrieve metadata for USGS monitoring sites using geographic filters (state, county, HUC).

### Get Near Real-Time Readings
Fetch current water levels and streamflow data at 15-minute intervals.

### Analyze Daily Trends
Retrieve daily summaries (min, max, mean) for historical flow rates and water levels over long periods.

### Calculate Aggregate Statistics
Generate monthly or annual statistical reports based on approved data sets.

### Track Groundwater Levels
Access historical, manually-recorded data specific to subsurface aquifer levels.

## Use Cases

### Assessing Flood Risk Before a Season
A civil engineer needs to know if the Potomac River has dropped below critical levels. They use `get_instantaneous_values` filtered by the relevant site ID and date range. The agent returns current gage height, allowing them to adjust construction plans immediately.

### Writing a Research Paper on Climate Change
An environmental scientist needs 10 years of data for one county. They first use `get_sites` to confirm the correct monitoring ID, then run `get_daily_values` and `get_statistics` across that ID for trend analysis.

### Checking on an Aquifer's Health
A municipal planner needs subsurface data. They bypass surface river flow and use `get_groundwater_levels`, specifying the required filter to track aquifer depletion trends over time, which is crucial for resource allocation.

### Quickly Checking River Conditions
An outdoor enthusiast needs to know if a local stream is safe. They prompt for current flow at a known site ID; the agent uses `get_instantaneous_values` and returns the immediate, actionable reading.

## Benefits

- Real-time monitoring is instant. Instead of manually checking a dashboard, you ask for `get_instantaneous_values` to get 15-minute interval readings right in your chat.
- Deep historical dives are simple. Use `get_daily_values` to pull daily summaries (mean/median) over years, letting you spot long-term trends without data cleaning headaches.
- Groundwater is separated from surface flow. The dedicated `get_groundwater_levels` tool keeps your aquifer data distinct and accurate for specialized analysis.
- Site discovery takes seconds. Use `get_sites` to filter monitoring stations by state, county, or HUC code—you never have to guess a site ID again.
- Annual reporting is automated. Running `get_statistics` generates monthly or annual summaries, saving hours of manual data aggregation for reports.

## How It Works

The bottom line is: you ask your AI client what water data you need, and it runs the correct query to pull clean, actionable USGS figures back to you.

1. First, prompt your agent with the required filters (e.g., site ID and date range) for the water data.
2. The server routes this request to the appropriate tool—like `get_daily_values` or `get_instantaneous_values`—and executes the query against public USGS sources.
3. You receive a structured dataset containing the specific hydrological metrics (e.g., gage height, flow cubic feet per second) for that period.

## Frequently Asked Questions

**How do I find a new USGS monitoring location using get_sites?**
Run `get_sites` and provide the filters you know—like State Code or county code. This tool returns metadata, including IDs for all active sites in that area.

**What's the difference between get_instantaneous_values and get_daily_values?**
Instantaneous values pull near real-time data (15-minute intervals). Daily values give you summarized records—the mean, max, min—for an entire 24-hour period.

**Can I get historical groundwater levels with the get_groundwater_levels tool?**
Yes. `get_groundwater_levels` is dedicated to pulling manually recorded data for subsurface aquifers, keeping it separate from typical surface streamflow readings.

**Which tool should I use if I need annual statistics?**
Use `get_statistics`. This tool specifically generates aggregated reports like daily, monthly, or annual stats, perfect for long-term trend analysis.

**What access key do I use when calling get_instantaneous_values?**
You must pass 'PUBLIC' as your access key. Since this server uses publicly available USGS data, you don't need to set up custom credentials or API keys for initialization. Just include that public string in the initial service call.

**What happens if I forget a required filter when using get_daily_values?**
The request fails because you must provide at least one major filter. The USGS API requires specific geographic or time constraints to run any query; don't try calling the tool without specifying location parameters.

**How do I calculate a specific metric, like the median flow rate, using get_statistics?**
You define the desired statistical aggregation within the call. When using `get_statistics`, specify 'median' or 'mean' for the metrics you need and provide the correct date range for accurate calculations.

**Should I combine multiple filters when searching sites with get_sites?**
Yes, combining filters improves accuracy and speed. Use AND logic by specifying both a State Code (stateCd) and a Hydrologic Unit Code (huc). This narrows the search to exactly what you need.

**How can I find all water monitoring sites in a specific state?**
Use the `get_sites` tool and provide the 2-digit USPS state code (e.g., 'CA' for California) in the `stateCd` parameter. This will return a list of sites and their metadata for that state.

**Can I get real-time streamflow data for a specific river station?**
Yes! Use `get_instantaneous_values` with the specific USGS site number in the `sites` parameter. You can also specify `parameterCd` as '00060' for discharge (streamflow).

**Is it possible to retrieve long-term monthly averages for a site?**
Absolutely. Use the `get_statistics` tool with the `statReportType` set to 'monthly'. This will provide approved statistical summaries based on the historical record of the site.