Usgs Water MCP

🚀 USGS Water MCP

This MCP server offers comprehensive access to USGS water data via three APIs, providing real - time water measurements, flood impact information, and geological metadata.

🚀 Quick Start

The server is modularly designed with a unified entry - point, making it easy to access different water - related data through a single interface.

✨ Features

• USGS Water Services API: Provides real - time water measurements such as stream flow, gage height, and temperature.
• Real - Time Flood Impacts API: Offers current flooding conditions and reference points.
• OGC API: Supplies monitoring location metadata, agency codes, and geological information.

📦 Installation

Installing via pip

pip install -e .

Manual Installation

1. Clone this repository.
2. Install dependencies:

pip install httpx mcp

💻 Usage Examples

Basic Usage

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"
        }
      ]
    }
  ]
}

📚 Documentation

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!

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:MM)
    • 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)

🔧 Technical Details

The server is modularly designed with separate API handlers unified through a single entry point (main.py). This design allows for easy maintenance and scalability.

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.