水利：水利水情监测预警

该 MCP 服务提供河流水情、水库水情、重点监测站、分省监测统计、降雨量 TOP10 和水情预警查询能力，用于水情信息检索与辅助研判。

主要功能

• 🌊 河流水情监测记录查询

• 🏞️ 水库水情监测记录查询

• 📍 重点监测站降雨记录查询

• 🗺️ 分省监测站与异常等级统计

• 🌧️ 指定统计日期降雨量 TOP10 查询

• ⚠️ 洪水、干旱预警记录查询

Related MCP server: Environment Agency Flood Monitoring MCP Server

工具速览

四个分页 Tool 只接受 pageIndex，不要传 page；pageIndex 默认 1、最小 1，pageSize 默认且最大为 10。

环境要求

• Python 3.10+

• 依赖包：python-dotenv、requests、mcp

本地快速启动

1. 克隆项目

GitHub（公开仓库）：

git clone https://github.com/handaas/hydrology-mcp-server.git
cd hydrology-mcp-server

也可以从 Gitee 克隆私有镜像；执行前需要获得仓库访问授权：

git clone https://gitee.com/handaas/hydrology-mcp-server.git
cd hydrology-mcp-server

以上地址是源码仓库，不是可直接连接的托管 MCP 服务地址。

2. 创建虚拟环境并安装依赖

python -m venv mcp_env
source mcp_env/bin/activate
pip install -r requirements.txt

3. 配置环境变量

cp .env.example .env

编辑 .env：

INTEGRATOR_ID=your_integrator_id
SECRET_ID=your_secret_id
SECRET_KEY=your_secret_key
HANDAAS_REQUEST_TIMEOUT=30
FASTMCP_PORT=8001

• INTEGRATOR_ID、SECRET_ID、SECRET_KEY：HandaaS 对接器认证信息。

• HANDAAS_REQUEST_TIMEOUT：可选，上游请求超时秒数，默认 30。

• FASTMCP_PORT：可选，本地 HTTP 监听端口，默认 8000；示例使用 8001，以减少与其他 MCP 服务的端口冲突。

认证信息需要登录 HandaaS 注册并开通对应数据产品后获取。不要提交 .env、真实凭据或真实业务响应。

服务启动时只自动读取本服务目录下的 .env。同名进程环境变量优先于 .env：适合在 CI 或 MCP 客户端中直接注入凭据。python server/mcp_server.py ... 可只使用进程环境变量，不强制要求 .env 文件；start_mcp_server.sh 则会先检查本目录的 mcp_env/ 和 .env，缺少任一项都会退出。

4. 启动服务

服务支持 stdio、sse 和 streamable-http 三种传输方式：

# STDIO
python server/mcp_server.py stdio

# Streamable HTTP
python server/mcp_server.py streamable-http

# SSE
python server/mcp_server.py sse

也可以使用启动脚本；省略参数时默认启动 streamable-http：

./start_mcp_server.sh
./start_mcp_server.sh stdio
./start_mcp_server.sh sse

使用示例端口 8001 时，Streamable HTTP MCP 地址为 http://127.0.0.1:8001/mcp。

• 直接运行 Python 且省略传输参数时，默认使用 stdio。

• 启动脚本省略传输参数时，默认使用 streamable-http。

• sse 和 streamable-http 固定监听 127.0.0.1；端口取 FASTMCP_PORT，未配置时为 8000。修改端口后应同步修改客户端 URL。

Cursor / Cherry Studio 配置

Streamable HTTP

先在项目目录启动 python server/mcp_server.py streamable-http，再添加：

{
  "mcpServers": {
    "hydrology-mcp-server": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}

STDIO

将 {workdir} 替换为 hydrology-mcp-server 的绝对路径：

{
  "mcpServers": {
    "hydrology-mcp-server": {
      "command": "{workdir}/mcp_env/bin/python",
      "args": ["{workdir}/server/mcp_server.py", "stdio"],
      "env": {
        "INTEGRATOR_ID": "your_integrator_id",
        "SECRET_ID": "your_secret_id",
        "SECRET_KEY": "your_secret_key",
        "HANDAAS_REQUEST_TIMEOUT": "30"
      }
    }
  }
}

使用官方 Remote 服务

当前服务尚未发布官方 Remote 地址。请使用本地 stdio、sse 或 streamable-http 方式运行；官方 Remote 地址发布后再补充远程配置。

推荐调用方式

1. 按河流、水库或重点站类型选择对应 Tool，不要混用不同记录类型的业务字段。

2. 需要区域筛选时，可在 province 或 basin 中用英文逗号分隔多个值，例如 湖北省,湖南省。

3. 需要最新降雨排行时省略 statDate，由上游选择最新统计日期；不要将运行 MCP 的计算机日期当作统计日期。

4. 预警结果必须结合 isHistory、releaseTime、endTime 和查询时刻判断是历史预警还是当前预警，并检查时间新鲜度。

响应约定

六个 Tool 成功时统一返回 total/resultList。以下内容是合成结构示例，不包含真实业务数据：

{
  "total": 1,
  "resultList": [
    {
      "province": "示例省",
      "stationName": "示例站",
      "recordTime": "2026-01-01 08:00:00",
      "waterLevel": 12.3,
      "warningWaterLevel": 0,
      "extraUpstreamField": "客户端应兼容的上游扩展字段"
    }
  ]
}

MCP 会保留 resultList 每条记录中的上游未知字段，不会为了匹配本文档而删除扩展字段；客户端应读取所需字段并容忍额外字段。total=0 且 resultList=[] 只表示当前筛选没有返回记录，不能解释为现实中没有水情风险。

参数校验、网关或上游错误返回包含 error 的对象，并可能附带 parameter、code、statusCode 或 diagnostic。例如，无效日期的合成错误结构为：

{
  "error": "startTime 必须为有效日期，格式 YYYY-MM-DD",
  "parameter": "startTime"
}

通过 MCP 调用时，类型、分页数值边界等 Schema 校验也可能在工具执行前直接返回 isError=true。客户端应同时处理 MCP 协议错误和 structuredContent 中的业务 error，不能只检查 HTTP 状态码。

可用工具

1. hydrology_river_monitoring_list

功能：分页查询河流水情监测记录。

数据产品 ID：6a76cb19dfa4a2f37b18fe70

参数：

• province（可选）：省份；多个值使用英文逗号分隔。

• basin（可选）：流域；多个值使用英文逗号分隔。

• riverName（可选）：河流名称，单个模糊查询字符串。

• stationName（可选）：监测站名称，单个模糊查询字符串。

• startTime（可选）：记录起始日期，严格使用 YYYY-MM-DD。

• endTime（可选）：记录结束日期，严格使用 YYYY-MM-DD，不能早于 startTime。

• pageIndex（可选）：页码，默认 1，最小 1。实际接口参数名是 pageIndex，不要传 page。

• pageSize（可选）：每页条数，默认 10，范围 1～10。

返回值：

• total：符合条件的河流监测记录总数。

• resultList：当前页记录列表。

  • basin：流域。

  • province：省份。

  • riverName：河流名称。

  • stationName：监测站名称。

  • recordTime：记录时间。

  • waterLevel：水位，浮点数，单位米。

  • warningWaterLevel：超警水位，浮点数，单位米；这是超出警戒水位的数值，0 表示未超警，不是警戒水位阈值。

说明：源 PDF 标注上游 pageSize 最大 50；MCP 为控制单次返回量，采用更保守的 1～10 限制。

2. hydrology_reservoir_monitoring_list

功能：分页查询水库水情监测记录。

数据产品 ID：6a76d075dfa4a2f37b18ff6c

参数：

• province（可选）：省份；多个值使用英文逗号分隔。

• basin（可选）：流域；多个值使用英文逗号分隔。

• riverName（可选）：河流名称，单个模糊查询字符串。

• stationName（可选）：监测站名称，单个模糊查询字符串。

• startTime（可选）：记录起始日期，严格使用 YYYY-MM-DD。

• endTime（可选）：记录结束日期，严格使用 YYYY-MM-DD，不能早于 startTime。

• pageIndex（可选）：页码，默认 1，最小 1。实际接口参数名是 pageIndex，不要传 page。

• pageSize（可选）：每页条数，默认 10，范围 1～10。

返回值：

• total：符合条件的水库监测记录总数。

• resultList：当前页记录列表。

  • basin：流域。

  • province：省份。

  • riverName：河流名称。

  • stationName：监测站名称。

  • recordTime：记录时间。

  • reservoirWaterLevel：水库水位，浮点数，单位米。

  • dailyRange：日变幅，浮点数，单位米；保留上游正负号，不转换为绝对值。

说明：源 PDF 标注上游 pageSize 最大 50；MCP 为控制单次返回量，采用更保守的 1～10 限制。

3. hydrology_key_station_list

功能：分页查询重点监测站降雨记录。

数据产品 ID：6a76d1318c8d379dd486a91d

参数：

• province（可选）：省份；多个值使用英文逗号分隔。

• basin（可选）：流域；多个值使用英文逗号分隔。

• riverName（可选）：河流名称，单个模糊查询字符串。

• stationName（可选）：监测站名称，单个模糊查询字符串。

• startTime（可选）：记录起始日期，严格使用 YYYY-MM-DD。

• endTime（可选）：记录结束日期，严格使用 YYYY-MM-DD，不能早于 startTime。

• pageIndex（可选）：页码，默认 1，最小 1。实际接口参数名是 pageIndex，不要传 page。

• pageSize（可选）：每页条数，默认 10，范围 1～10。

返回值：

• total：符合条件的重点站记录总数。

• resultList：当前页记录列表。

  • basin：流域。

  • province：省份。

  • riverName：河流名称。

  • stationName：监测站名称。

  • recordTime：记录时间。

  • dailyRainfall：日降雨量，浮点数，单位毫米；0 表示无降雨。

说明：源 PDF 标注上游 pageSize 最大 50；MCP 为控制单次返回量，采用更保守的 1～10 限制。

4. hydrology_province_statistics

功能：查询分省监测站数量、当前预警数量及水情异常等级。

数据产品 ID：6a76d2d68c8d379dd486a955

参数：

• province（可选）：省份；多个值使用英文逗号分隔。省略时查询全部省份。

返回值：

• total：规范化后的省份统计记录数。

• resultList：省份统计列表。上游直接返回单个对象时，MCP 包装为 total=1 和 resultList=[record]；上游返回列表或分页结构时也统一为该格式。

  • province：省份。

  • totalStations：监测站总数，整数计数。

  • riverMonitorStations：河流水情监测站数量，整数计数。

  • largeReservoirStations：大型水库监测站数量，整数计数。

  • keyStations：重点监测站数量，整数计数。

  • currentWarnings：当前预警数量，整数计数。

  • riverInflowAnomalyLevel：河流来水异常等级，字符串；源文档未给出固定枚举。

  • reservoirStorageAnomalyLevel：水库蓄水异常等级，字符串；源文档未给出固定枚举。

  • soilMoistureAnomalyLevel：土壤墒情异常等级，字符串；源文档未给出固定枚举。

说明：源 PDF 同时描述“全部省份”查询和单个 data 对象，响应形态存在歧义。2026-09-08 真实网关实测 data 为列表，不筛选时返回34条；单省及多省筛选均通过。单对象、分页外层兼容分支有离线测试覆盖，未声称上游实际使用这些变体。

5. hydrology_rainfall_top10

功能：查询指定统计日期或上游最新统计日期的日降雨量 TOP10。

数据产品 ID：6a76d3d18c8d379dd486a972

参数：

• statDate（可选）：统计日期，严格使用 YYYY-MM-DD。省略时由上游选择最新统计日期，不等同于运行 MCP 的计算机当天日期。

返回值：

• total：当前 TOP 列表长度，不是全国监测站总数。

• resultList：上游 data.topRainList，保持原顺序；源文档说明按 dailyRainfall 从高到低排列。

  • basin：流域。

  • province：省份。

  • riverName：河流名称。

  • stationName：监测站名称。

  • recordTime：记录时间。

  • dailyRainfall：日降雨量，数值，单位毫米。

说明：该 Tool 没有分页参数。MCP 不重新排序或补齐记录，直接保留上游 TOP 列表顺序。

6. hydrology_warning_list

功能：分页查询洪水或干旱预警记录。

数据产品 ID：6a76d4df8c8d379dd486a97e

参数：

• warningLevel（可选）：预警等级；可使用 red、orange、yellow、blue，多个值使用英文逗号分隔。

• warningType（可选）：预警类型，单个值，仅支持 flood 或 drought。

• startTime（可选）：预警发布时间范围起始日期，严格使用 YYYY-MM-DD。

• endTime（可选）：预警发布时间范围结束日期，严格使用 YYYY-MM-DD，不能早于 startTime。

• pageIndex（可选）：页码，默认 1，最小 1。实际接口参数名是 pageIndex，不要传 page。

• pageSize（可选）：每页条数，默认 10，范围 1～10。

返回值：

• total：符合条件的预警记录总数。

• resultList：当前页预警记录列表。

  • level：预警等级。

  • type：预警类型。

  • title：预警标题。

  • unitName：发布单位名称。

  • unitNameId：发布单位 ID。

  • releaseTime：发布时间。

  • endTime：结束时间。

  • affectedRange：影响范围。

  • detail：预警详情。

  • isHistory：是否为历史预警，布尔值。

说明：源 PDF 标注上游 pageSize 最大 20；MCP 为控制单次返回量，采用更保守的 1～10 限制。不能只凭标题判断预警是否仍然有效，必须结合 isHistory、发布时间、结束时间和查询时刻判断。

使用注意事项

1. 分页边界：四个分页 Tool 的 MCP pageSize 都限制为 1～10。三个监测接口的源 PDF 上游上限为 50，预警接口的源 PDF 上游上限为 20；MCP 的保守上限不代表上游原始上限。

2. 分页参数名：四个分页 Tool 统一使用 pageIndex，不支持 page。源 PDF 中的 page 已被 2026-09-08 用户提供的实际接口更正取代；以本 README 和当前 MCP Schema 的 pageIndex 为准。

3. 日期格式：所有日期参数必须严格使用 YYYY-MM-DD，日期范围起点不能晚于终点。

4. 多值格式：province、basin、warningLevel 的多个值使用英文逗号分隔；riverName、stationName 和 warningType 只接受单个查询字符串。

5. 字段语义：warningWaterLevel 表示超警水位，0 表示未超警；dailyRange 保留正负号；dailyRainfall=0 表示无降雨。

6. 统一响应：六个 Tool 成功时均统一返回 total/resultList。分省统计会兼容上游单对象、列表与分页结构；降雨 TOP10 的 total 仅是当前排行列表长度。

7. 时间新鲜度：监测记录与预警都可能是历史数据。使用结论前应核对 recordTime、releaseTime、endTime 和 isHistory。

8. 空结果边界：空响应只表示当前筛选条件下没有返回记录，不能据此断言没有洪水、干旱、超警或其他现实风险。

9. 能力边界：本服务是按请求查询的只读接口，不是风险预测引擎，不执行定时监测，不发布告警，也不提供应急决策保证。

10. 验证状态：六个 Tool 已取得真实非空样本，2026-09-09 已完成六接口连接与返回数据复检。

使用提问示例

hydrology_river_monitoring_list（河流水情监测）

1. 查询长江流域湖北省最近一周的河流水位记录

2. 搜索河流名称中包含“黄河”的监测站，并查看是否存在超警水位

3. 使用 pageIndex=2 查询指定日期范围内某监测站的第 2 页记录，每页 10 条

hydrology_reservoir_monitoring_list（水库水情监测）

1. 查询广东省水库最近 7 天的水位和日变幅

2. 查看珠江流域各水库监测站的最新记录

3. 使用 pageIndex=2 继续查询站名中包含“三峡”的水库水情，并保留日变幅正负号

hydrology_key_station_list（重点监测站）

1. 查询湖南省重点监测站最近一周的日降雨量

2. 查询长江流域重点站记录，再在已读取分页中筛选日降雨量大于 0 的记录

3. 搜索站名中包含“武汉”的重点监测站，并用 pageIndex=2 查询第 2 页

hydrology_province_statistics（分省水情统计）

1. 查询全国各省监测站数量和当前预警数量

2. 对比湖北省和湖南省的河流监测站、水库监测站及重点站数量

3. 查看四川省河流来水、水库蓄水和土壤墒情异常等级

hydrology_rainfall_top10（降雨量 TOP10）

1. 查询上游最新统计日期的日降雨量 TOP10

2. 查看 2026-09-08 日降雨量最高的 10 个监测站

3. 列出指定日期 TOP10 的省份、流域、站名和降雨量

hydrology_warning_list（水情预警）

1. 查询最近 7 天的红色和橙色洪水预警

2. 查看指定日期范围内的干旱预警，并区分历史预警和当前预警

3. 使用 pageIndex=2 查询蓝色和黄色预警的发布单位、影响范围及结束时间

测试验证

离线测试不需要真实凭据：

python -m py_compile server/mcp_server.py
python -m unittest discover -s tests -p 'test_*.py' -v

真实接口 smoke 测试必须显式传入 --live，并通过实际 MCP STDIO 会话完成初始化、Tool 调用和响应检查：

python tests/live_api_smoke.py --live

如需读取其他环境文件，可显式指定：

python tests/live_api_smoke.py --live --env-file /path/to/hydrology.env

显式指定 --env-file 时，脚本只在内存中读取该凭据文件，不复制到服务目录；文件中的值会写入测试子进程环境，并优先于同名当前环境变量。不要提交凭据文件。

smoke 测试只应输出去标识化的记录数量、字段名和延迟，不输出业务记录内容、请求签名或凭据。空结果是合法接口结果，测试应标记“未取得非空样本”，不能据此判断现实中没有风险。

2026-09-08 本地验证：28 个离线测试通过，包含真实 STDIO、SSE、Streamable HTTP 传输与合成上游响应的端到端测试；Ruff、Python 语法检查、Shell 语法检查和 mypy 检查通过（mypy 跳过未安装的第三方 requests stubs）。四个分页工具的 Schema 与请求键均已验证为 pageIndex。

2026-09-08 真实验证：STDIO 基线6/6通过且都有非空样本。HTTP 功能检查覆盖六个工具、单省/多省及流域筛选、模糊搜索、日期区间、分页大小与翻页、空结果、降雨排序、预警类型/等级、非法日期及参数边界。

2026-09-09 复检中六个 Tool 再次全部取得非空结果。

仓库内的 tests/live_api_smoke.py 每次只执行六个 Tool 的基线调用，不等同于全面功能验证。详细测试报告保留在开发工作区，不作为独立源码仓库文件发布。

接口源文档日期为2026-09-08，页码参数以用户同日提供的实际接口更正为准。测试只验证所覆盖场景，不代表遍历了全部水情记录或确认现实中没有风险。

常见问题

没有配置认证信息

Tool 会返回 INTEGRATOR_ID 未配置、SECRET_ID 未配置 或 SECRET_KEY 未配置。在本服务目录配置 .env，或通过启动进程 / MCP 客户端的环境变量注入；不要把真实凭据写入 README 或提交到仓库。

已配置凭据，但上游仍返回业务错误

确认当前 HandaaS 对接器已经开通本 README 所列数据产品权限。服务会保留上游业务错误的 code 和消息；产品未授权时不要修改 Product ID、签名逻辑或伪造空结果。

参数被拒绝

分页参数必须使用 pageIndex，不能使用 page；pageIndex>=1，pageSize 范围为1～10。日期必须是有效的 YYYY-MM-DD，起始日期不能晚于结束日期；枚举和多值格式见对应 Tool 参数表。

返回 405 或 HTML 响应

检查 console.handaas.com 的 DNS、PAC / 透明代理规则，以及网络是否允许向网关发送 POST。该诊断只说明连接路径需要排查，不代表凭据或产品权限有效。

本地端口冲突

为 sse 或 streamable-http 设置一个未占用的 FASTMCP_PORT，然后同步修改客户端 URL。stdio 不需要 HTTP 监听端口。

接口资料依据

接口说明依据父工作区 doc/水利水情监测预警/ 下列文档整理；这些 PDF 不复制到独立源码仓库，也不在此创建可能失效的相对链接：

• 江河监测数据明细_2026-09-08_16-44-02.pdf

• 大型水库数据明细_2026-09-08_16-44-09.pdf

• 重点站点数据明细_2026-09-08_16-44-13.pdf

• 水利水情省份分布统计_2026-09-08_16-44-17.pdf

• 重点站日降雨量TOP10_2026-09-08_16-44-26.pdf

• 全国水情预警明细_2026-09-08_16-44-30.pdf