内容
# 地下水MCP
> 一个开源的Python MCP服务器，用于AI辅助地下水建模，支持MODFLOW 6、FloPy、PEST++、pyEMU和UCODE。
无需等待列表。无需付费墙。无封闭组件。完全在您的机器上运行。
---
## 功能介绍
地下水MCP连接任何MCP兼容的AI助手（Claude、Cursor等）到完整的地下水建模栈。您可以要求AI从现实世界的数据中建立模型，运行模型，检查结果，并校准参数 — 所有这些都可以通过自然语言完成，实际计算通过FloPy和MODFLOW 6在本地进行。
```
我有一个DEM栅格，一个包含K值的地质分区shapefile，
钻孔水位CSV文件和一个河流中心线shapefile。
建立一个3层的流域瞬态模型，运行2年，
根据观测水头校准，并绘制水量平衡图。」
```
### 范围
地下水MCP涵盖地下水工作流的*建模*方面：从处理的空间数据中参数化模型，运行模拟，处理结果和校准参数。
上游数据准备 — 裁剪DEMs，克里金插值钻孔日志，处理气候数据 — 被故意排除在此范围之外。这项工作属于配套的`geodata-mcp`（计划中）。两者之间的接口很简单：地下水MCP接受标准文件格式（GeoTIFF，GeoPackage/Shapefile，CSV）作为其参数化工具的输入。
---
## 工具（共36个）
| 模块 | 工具 |
|---|---|
| **文档** | `搜索文档`，`搜索教程`，`获取文档文件` |
| **参数化** | `从shapefile导入网格`，`从栅格分配顶部`，`从区域分配K值`，`从shapefile导入河流`，`从CSV导入观测数据` |
| **模型构建** | `创建模型`，`设置模拟`，`添加离散包`，`添加离散变量包`，`添加npf包`，`添加初始条件包`，`添加边界包`，`添加观测包`，`总结模型`，`列出模型文件` |
| **运行** | `检查模型`，`运行模拟`，`获取运行日志` |
| **后处理** | `读取水头`，`读取预算`，`计算降深`，`计算水量平衡`，`绘制水头地图`，`绘制剖面图` |
| **校准（PEST++）** | `设置PEST控制文件`，`运行PEST++glm`，`运行PEST++ies`，`总结校准`，`运行IES不确定性分析` |
| **校准（UCODE）** | `设置UCODE控制文件`，`运行UCODE`，`总结UCODE校准`，`运行UCODE不确定性分析` |
参见 [TOOLS.md](TOOLS.md) 获取完整的输入/输出文档。
---
## 安装
```bash
# 1. 安装软件包
pip install groundwater-mcp
# 2. 下载MODFLOW 6二进制文件
get-modflow :
# 3. 下载PEST++二进制文件（用于校准）
get-pestpp :
# 4. 构建本地文档搜索索引
groundwater-mcp build-index
```
### Claude Desktop 配置
添加到 `~/.config/claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"groundwater": {
"command": "groundwater-mcp",
"args": ["serve"]
}
}
}
```
---
## 需求
- Python 3.11+
- flopy ≥ 3.7
- geopandas, rasterio（用于参数化工具）
- MODFLOW 6 二进制文件（通过 `get-modflow`）
- pyemu（用于PEST++校准工具）
- PEST++ 二进制文件（用于PEST++校准工具）
- UCODE_2014 二进制文件（用于UCODE校准工具；从 https://geology.mines.edu/igwmc/ucode/ 下载）
---
## 项目文件
| 文件 | 内容 |
|---|---|
| [ARCHITECTURE.md](ARCHITECTURE.md) | 系统设计，模块职责，文件结构，技术栈 |
| [TOOLS.md](TOOLS.md) | 完整的工具参考：输入，输出，错误代码 |
| [TASKS.md](TASKS.md) | 分阶段实施计划，带有复选框 |
---
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
---
## 致谢
建立在开源地下水建模社区的肩膀上：
[USGS MODFLOW](https://www.usgs.gov/mission-areas/water-resources/science/modflow-and-related-programs) ·
[FloPy](https://github.com/modflowpy/flopy) ·
[PEST++](https://github.com/usgs/pestpp) ·
[pyEMU](https://github.com/pypest/pyemu)
