美国地质调查局水资源MCP服务器

Name: 美国地质调查局水资源MCP服务器
Author: pgiffy

作者：pgiffy2 星标更新：2025-07-16

安装使用来源：spider==github.com

项目介绍

USGS Water MCP

概述

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

USGS Water Services API - 实时水测量数据（如流速、水位、温度等）
实时洪水影响API - 当前洪水状况和参考点
OGC API - 监测位置元数据、机构代码和地质信息

该服务器采用模块化设计，通过单一入口点统一各个API处理器。

项目结构

usgs-water-mcp/
├── main.py                  # 统一入口点
├── water_data_api.py        # USGS Water Services API工具
├── flood_impact_api.py      # 实时洪水影响API工具
├── ogc_api.py              # OGC API工具
├── current_water_levels.py  # 遗留组合文件（已弃用）
├── Dockerfile              # Docker配置
├── pyproject.toml          # 项目依赖
└── README.md               # 此文件

服务

如果您想要一个干净的Web界面来利用这些工具，请访问 https://aqua-node.onrender.com/landing 并帮助我进行一些测试！

示例输出

以下是从Potomac河获取流速数据的示例：

{
  "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": "流量，每秒立方英尺"
      }
    ]
  },
  "values": [
    {
      "value": [
        {
          "value": "6420",
          "qualifiers": ["A"],
          "dateTime": "2023-10-01T12:00:00.000"
        }
      ]
    }
  ]
}

安装

通过pip安装

pip install -e .

手动安装

克隆此仓库
安装依赖项：
```
pip install httpx mcp
```

连接至Claude Desktop

编辑您的Claude Desktop配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%/Claude/claude_desktop_config.json

添加服务器配置：

{
  "mcpServers": {
    "usgs-water": {
      "command": "python",
      "args": ["/path/to/usgs-water-mcp/main.py"]
    }
  }
}

重启Claude Desktop

可用工具

水文数据工具

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值

示例用法：

获取华盛顿特区附近Potomac河的当前流速：
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

根据ID获取特定州的信息。

参数：

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

get_counties

获取县列表。

get_counties_by_state

获取特定州的县。

参数：

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

get_nws_usgs_crosswalk

获取NWS/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）

故障排除

常见问题

API连接错误：确保您有活动的互联网连接且可以访问USGS API
无效站点编号：使用USGS国家水资源数据网站验证站点编号是否存在
无可用数据：某些站点可能没有请求时间段或参数的数据
速率限制：USGS API有使用限制；避免在短时间内发送过多请求

查找站点编号

使用 USGS国家水资源数据网站查找您感兴趣的区域内的监测站站点编号。