About
该MCP服务提供江河、水库、重点站监测、省份统计、降雨TOP10和水情预警查询,帮助用户开展水情检索与辅助研判。
README
该 MCP 服务提供河流水情、水库水情、重点监测站、分省监测统计、降雨量 TOP10 和水情预警查询能力,用于水情信息检索与辅助研判。
主要功能
- 🌊 河流水情监测记录查询
- 🏞️ 水库水情监测记录查询
- 📍 重点监测站降雨记录查询
- 🗺️ 分省监测站与异常等级统计
- 🌧️ 指定统计日期降雨量 TOP10 查询
- ⚠️ 洪水、干旱预警记录查询
工具速览
| Tool | 用途 | 关键参数 | 分页 |
|---|---|---|---|
hydrology_river_monitoring_list |
查询江河水位与超警水位 | province、basin、riverName、stationName、日期范围 |
pageIndex / pageSize |
hydrology_reservoir_monitoring_list |
查询大型水库水位与日变幅 | province、basin、riverName、stationName、日期范围 |
pageIndex / pageSize |
hydrology_key_station_list |
查询重点站日降雨量 | province、basin、riverName、stationName、日期范围 |
pageIndex / pageSize |
hydrology_province_statistics |
查询分省站点、预警与异常等级统计 | province |
不分页 |
hydrology_rainfall_top10 |
查询指定日期或上游最新日期的降雨量 TOP10 | statDate |
不分页 |
hydrology_warning_list |
查询洪水、干旱预警 | warningLevel、warningType、日期范围 |
pageIndex / pageSize |
四个分页 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 地址发布后再补充远程配置。
推荐调用方式
- 按河流、水库或重点站类型选择对应 Tool,不要混用不同记录类型的业务字段。
- 需要区域筛选时,可在
province或basin中用英文逗号分隔多个值,例如湖北省,湖南省。 - 需要最新降雨排行时省略
statDate,由上游选择最新统计日期;不要将运行 MCP 的计算机日期当作统计日期。 - 预警结果必须结合
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、发布时间、结束时间和查询时刻判断。
使用注意事项
- 分页边界:四个分页 Tool 的 MCP
pageSize都限制为 1~10。三个监测接口的源 PDF 上游上限为 50,预警接口的源 PDF 上游上限为 20;MCP 的保守上限不代表上游原始上限。 - 分页参数名:四个分页 Tool 统一使用
pageIndex,不支持page。源 PDF 中的page已被 2026-09-08 用户提供的实际接口更正取代;以本 README 和当前 MCP Schema 的pageIndex为准。 - 日期格式:所有日期参数必须严格使用
YYYY-MM-DD,日期范围起点不能晚于终点。 - 多值格式:
province、basin、warningLevel的多个值使用英文逗号分隔;riverName、stationName和warningType只接受单个查询字符串。 - 字段语义:
warningWaterLevel表示超警水位,0表示未超警;dailyRange保留正负号;dailyRainfall=0表示无降雨。 - 统一响应:六个 Tool 成功时均统一返回
total/resultList。分省统计会兼容上游单对象、列表与分页结构;降雨 TOP10 的total仅是当前排行列表长度。 - 时间新鲜度:监测记录与预警都可能是历史数据。使用结论前应核对
recordTime、releaseTime、endTime和isHistory。 - 空结果边界:空响应只表示当前筛选条件下没有返回记录,不能据此断言没有洪水、干旱、超警或其他现实风险。
- 能力边界:本服务是按请求查询的只读接口,不是风险预测引擎,不执行定时监测,不发布告警,也不提供应急决策保证。
- 验证状态:六个 Tool 已取得真实非空样本,2026-09-09 已完成六接口连接与返回数据复检。
使用提问示例
hydrology_river_monitoring_list(河流水情监测)
- 查询长江流域湖北省最近一周的河流水位记录
- 搜索河流名称中包含“黄河”的监测站,并查看是否存在超警水位
- 使用
pageIndex=2查询指定日期范围内某监测站的第 2 页记录,每页 10 条
hydrology_reservoir_monitoring_list(水库水情监测)
- 查询广东省水库最近 7 天的水位和日变幅
- 查看珠江流域各水库监测站的最新记录
- 使用
pageIndex=2继续查询站名中包含“三峡”的水库水情,并保留日变幅正负号
hydrology_key_station_list(重点监测站)
- 查询湖南省重点监测站最近一周的日降雨量
- 查询长江流域重点站记录,再在已读取分页中筛选日降雨量大于 0 的记录
- 搜索站名中包含“武汉”的重点监测站,并用
pageIndex=2查询第 2 页
hydrology_province_statistics(分省水情统计)
- 查询全国各省监测站数量和当前预警数量
- 对比湖北省和湖南省的河流监测站、水库监测站及重点站数量
- 查看四川省河流来水、水库蓄水和土壤墒情异常等级
hydrology_rainfall_top10(降雨量 TOP10)
- 查询上游最新统计日期的日降雨量 TOP10
- 查看 2026-09-08 日降雨量最高的 10 个监测站
- 列出指定日期 TOP10 的省份、流域、站名和降雨量
hydrology_warning_list(水情预警)
- 查询最近 7 天的红色和橙色洪水预警
- 查看指定日期范围内的干旱预警,并区分历史预警和当前预警
- 使用
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
Installing Hydrology
This server has no published package — it is built from source. Open the repository and follow its README.
▸ github.com/handaas/hydrology-mcp-serverFAQ
Is Hydrology MCP free?
Yes, Hydrology MCP is free — one-click install via Unyly at no cost.
Does Hydrology need an API key?
No, Hydrology runs without API keys or environment variables.
Is Hydrology hosted or self-hosted?
Self-hosted: the server runs locally on your machine via the install command above.
How do I install Hydrology in Claude Desktop, Claude Code or Cursor?
Open Hydrology on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.
Related MCPs
GitHub
PRs, issues, code search, CI status
by GitHubFilesystem
Secure file operations with configurable access controls.
Memory
Knowledge graph-based persistent memory system.
Unyly Deploy
Deploy sites and MCP servers to Unyly straight from your AI agent
by UnylyTemplate MCP Server
A CLI tool to create a new Model Context Protocol server project with TypeScript support, dual transport options, and an extensible structure
by mcpdotdirectServer Sequential Thinking
MCP server for sequential thinking and problem solving
by GitHub ActionsAmap Maps Mcp Server
MCP server for using the AMap Maps API
by duxiaohuiPayMCP
Lightweight payments layer for MCP servers: turn tools into paid endpoints with a two-line decorator. [PyPI](https://pypi.org/project/paymcp/) · [npm](https://w
by blustAIdemo
demo — MCP server via Smithery
by yoojoohans-jpgServer For Power BI
Enables exploring Microsoft Fabric / Power BI workspaces and semantic models, and executing ad-hoc DAX queries.
by Mitsubishi-FusoCompare Hydrology with
Not sure what to pick?
Find your stack in 60 seconds
Author?
Embed badge for your README
Browse similar
All development MCPs
