Skip to main content
Glama

USGS Water MCP

by pgiffy

USGS Water MCP

Overview

This MCP server provides comprehensive access to USGS water data through three APIs:

  1. USGS Water Services API - Real-time water measurements (stream flow, gage height, temperature, etc.)
  2. Real-Time Flood Impacts API - Current flooding conditions and reference points
  3. 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

usgs-water-mcp/ ├── main.py # Unified entry point ├── water_data_api.py # USGS Water Services API tools ├── flood_impact_api.py # Real-Time Flood Impacts API tools ├── ogc_api.py # OGC API tools ├── current_water_levels.py # Legacy combined file (deprecated) ├── Dockerfile # Docker configuration ├── pyproject.toml # Project dependencies └── README.md # This file

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:

{ "name": "USGS:01646500:00060:00000", "sourceInfo": { "siteName": "POTOMAC RIVER NEAR WASHINGTON, DC", "siteCode": [ { "value": "01646500", "network": "NWIS", "agencyCode": "USGS" } ] }, "variable": { "variableCode": [ { "value": "00060", "network": "NWIS", "vocabulary": "NWIS:UnitValues", "variableName": "Streamflow, ft�/s", "variableDescription": "Discharge, cubic feet per second" } ] }, "values": [ { "value": [ { "value": "6420", "qualifiers": ["A"], "dateTime": "2023-10-01T12:00:00.000" } ] } ] }

Installation

Installing via pip

pip install -e .

Manual Installation

  1. Clone this repository
  2. Install dependencies:
    pip install httpx mcp

Connecting with Claude Desktop

  1. Edit your Claude Desktop configuration file:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%/Claude/claude_desktop_config.json
  2. Add the server configuration:
    { "mcpServers": { "usgs-water": { "command": "python", "args": ["/path/to/usgs-water-mcp/main.py"] } } }
  3. 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 format
  • period (optional): Period code (e.g., "P7D" for 7 days)

Common Parameter Codes:

  • 00060: Discharge (stream flow)
  • 00065: Gage height
  • 00010: Temperature, water
  • 00300: Dissolved oxygen
  • 00400: pH

Example Usage:

Get current stream flow for the Potomac River near Washington, DC: sites: "01646500" parameter_codes: "00060"

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 code
  • site_type_code (optional): Filter by site type code
  • monitoring_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

  1. API Connection Errors: Ensure you have an active internet connection and the USGS API is accessible
  2. Invalid Site Numbers: Verify site numbers exist using the USGS Water Data for the Nation website
  3. No Data Available: Some sites may not have data for the requested time period or parameters
  4. 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.

-
security - not tested
F
license - not found
-
quality - not tested

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.

  1. Overview
    1. Project Structure
      1. Service
        1. Sample Output
          1. Installation
            1. Installing via pip
            2. Manual Installation
          2. Connecting with Claude Desktop
            1. Available Tools
              1. Water Data Tools
              2. Real-Time Flood Impact Tools
              3. OGC API Tools
            2. Troubleshooting
              1. Common Issues
              2. Finding Site Numbers

            Related MCP Servers

            • A
              security
              A
              license
              A
              quality
              Provides 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 -
              6
              3,041
              20
              TypeScript
              MIT License
            • -
              security
              A
              license
              -
              quality
              Real-time hydrological information retrieval service that provides water level, precipitation, dam discharge data, and observatory location information.
              Last updated -
              1
              Python
              Apache 2.0
              • Linux
              • Apple
            • A
              security
              A
              license
              A
              quality
              This 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 -
              15
              13
              3
              TypeScript
              MIT License
            • -
              security
              F
              license
              -
              quality
              Provides 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

            View all related MCP servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/pgiffy/usgs-water-mcp'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server