usgs-water-mcp

🚀 USGS Water MCP

本项目提供了一个MCP服务器，可通过三个API全面访问美国地质调查局（USGS）的水资源数据，为水资源相关的研究、监测和决策提供有力支持。

🚀 快速开始

若你想使用一个简洁的Web界面来调用这些工具，请访问 https://aqua-node.onrender.com/landing 并协助我进行一些测试！

✨ 主要特性

此MCP服务器通过三个API提供对USGS水资源数据的全面访问：

1. USGS Water Services API - 实时水资源测量数据（如水流、水位、温度等）
2. Real-Time Flood Impacts API - 当前洪水状况和参考点
3. OGC API - 监测位置元数据、机构代码和地质信息

服务器采用模块化设计，通过单个入口点统一不同的API处理程序。

📦 安装指南

通过pip安装

pip install -e .

手动安装

1. 克隆此仓库
2. 安装依赖项：

pip install httpx mcp

💻 使用示例

基础用法

以下是一个获取波托马克河水流数据的示例：

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

📚 详细文档

项目结构

usgs-water-mcp/
├── main.py                  # 统一入口点
├── water_data_api.py        # USGS Water Services API工具
├── flood_impact_api.py      # Real-Time Flood Impacts API工具
├── ogc_api.py               # OGC API工具
├── current_water_levels.py  # 旧的组合文件（已弃用）
├── Dockerfile               # Docker配置
├── pyproject.toml           # 项目依赖项
└── README.md                # 本文件

可用工具

水资源数据工具

fetch_usgs_data

从USGS监测站获取即时水资源数据。 参数：

• sites（必需）：以逗号分隔的站点编号（例如，"01646500" 或 "01646500,01647000"）
• parameter_codes（可选）：以逗号分隔的参数代码（例如，"00060,00065"）
• start_date（可选）：ISO格式的开始日期（YYYY-MM-DD 或 YYYY-MM-DDTHH:MM）
• end_date（可选）：ISO格式的结束日期
• period（可选）：周期代码（例如，"P7D" 表示7天）

常见参数代码：

• 00060：流量（水流）
• 00065：水位
• 00010：水温
• 00300：溶解氧
• 00400：pH值

使用示例：

获取华盛顿特区附近波托马克河的当前水流：
sites: "01646500"
parameter_codes: "00060"

实时洪水影响工具

get_flooding_reference_points

获取当前正在发生洪水的参考点（每30分钟更新一次）。

get_reference_points

获取参考点的分页列表。 参数：

• page（可选）：页码（默认值：1）
• limit（可选）：每页的结果数量（默认值：100）

get_reference_point_by_id

通过ID获取特定的参考点。 参数：

• reference_point_id（必需）：参考点ID

get_reference_points_by_state

获取特定州的参考点。 参数：

• state_id（必需）：州ID（例如，"CA"，"TX"）

get_reference_point_by_nwis_id

通过USGS水位计ID获取参考点。 参数：

• nwis_id（必需）：USGS国家水资源信息系统站点ID

get_reference_points_by_nws_id

通过国家气象局ID获取参考点。 参数：

• nws_id（必需）：国家气象局位置ID

get_inactive_reference_points

获取非活动参考点。

get_states

获取州列表。

get_state_by_id

获取特定州的信息。 参数：

• state_id（必需）：州ID（例如，"CA"，"TX"）

get_counties

获取县列表。

get_counties_by_state

获取特定州的县。 参数：

• state_id（必需）：州ID（例如，"CA"，"TX"）

get_nws_usgs_crosswalk

获取国家气象局/USGS交叉引用数据。

OGC API工具

get_monitoring_locations

获取具有广泛过滤选项的监测位置。 参数：

• bbox（可选）：以 "minx,miny,maxx,maxy" 表示的边界框
• limit（可选）：最大结果数量（默认值：100）
• offset（可选）：分页的起始偏移量（默认值：0）
• agency_code（可选）：按机构代码过滤（例如，"USGS"）
• state_code（可选）：按州代码过滤（例如，"CA"）
• county_code（可选）：按县代码过滤
• site_type_code（可选）：按站点类型代码过滤
• monitoring_location_number（可选）：特定的监测位置编号

get_monitoring_location_by_id

通过ID获取特定的监测位置。 参数：

• location_id（必需）：监测位置ID

get_agency_codes

获取机构识别代码。 参数：

• limit（可选）：最大结果数量（默认值：100）
• offset（可选）：分页的起始偏移量（默认值：0）

get_altitude_datums

获取垂直基准信息（推荐：NAVD88）。 参数：

• limit（可选）：最大结果数量（默认值：100）
• offset（可选）：分页的起始偏移量（默认值：0）

get_aquifer_codes

获取含水层识别信息。 参数：

• limit（可选）：最大结果数量（默认值：100）
• offset（可选）：分页的起始偏移量（默认值：0）

get_aquifer_types

获取含水层类型信息（承压与非承压）。 参数：

• limit（可选）：最大结果数量（默认值：100）
• offset（可选）：分页的起始偏移量（默认值：0）

get_coordinate_accuracy_codes

获取经纬度值的坐标精度代码。 参数：

• limit（可选）：最大结果数量（默认值：100）
• offset（可选）：分页的起始偏移量（默认值：0）

🔧 技术细节

常见问题

1. API连接错误：确保你有活跃的互联网连接，并且USGS API可访问。
2. 无效的站点编号：使用 USGS Water Data for the Nation 网站验证站点编号是否存在。
3. 无可用数据：某些站点可能在请求的时间段或参数下没有数据。
4. 速率限制：USGS API有使用限制；避免连续快速发出过多请求。

查找站点编号

使用 USGS Water Data for the Nation 网站查找你感兴趣区域的监测站站点编号。

徽章