SWMM-MCP
SWMM-MCP的 通过模型上下文协议（MCP）控制和后期处理EPA-SWMM模型的Python服务器是。\ swmm-api 0.4.69基于，可在MCP客户端上直接使用SWMM执行、结果时间序列提取、图形生成、GeoPackage/Parquet导出等。
______________________________________________________________________
1.主要功能
- 自动识别SWMM项目
- .inp 文件或 .inp只包含一个文件夹 project_path如果指定为 - 对应的 .rpt, .out 自动确定路径
- 查看INP结构
- list_nodes ：JUNCTION节点ID列表 - list_links ：CONDUIT链接ID列表 - list_subcatchments ：SUBCATCHMENT ID列表 - summarize_inp_basic ：节点、链接、流域数量摘要
- 运行SWMM
- run_swmm : swmm5.exe调用运行模型，返回stdout/stderr
- 查询OUT结果
- get_node_timeseries ：每个节点的水位/流量等时间序列 - get_link_timeseries ：各链路的流量/水深等时间序列 - get_subcatchment_timeseries ：各流域的流出量等时间序列
- 显示OUT结果
- plot_node_timeseries ：创建节点时间序列图（PNG） - plot_link_timeseries ：创建链接时间序列图（PNG）
- 分析RPT报告
- summarize_report ：错误和警告计数、代表性消息、最后N行摘要
- 导出以连接外部工具
- export_inp_to_geopackage ：INP→ GeoPackage(.gpkg）转换（用于QGIS） - export_out_to_parquet ：OUT→ 拼花地板(.parquet）转换（后处理，用于ML）
______________________________________________________________________
2.要求
- Python 3.10+
- 紫外线 （虚拟环境和包管理）
- 必需的软件包
- fastmcp - swmm-api[full]==0.4.69 - pandas - matplotlib
- EPA SWMM引擎
- 例如) C:\Program Files\EPA SWMM 5.2\swmm5.exe
______________________________________________________________________
3.安装方法
# 1) 저장소 클론
git clone https://github.com/choym01691-netizen/SWMM-Controller-MCP-.git/SWMM-MCP.git
cd SWMM-MCP
# 2) uv 프로젝트 초기화 (처음 한 번만)
uv init --package swmm-mcp
# 3) 필요한 패키지 설치
uv add swmm-api fastmcp pandas matplotlib4.运行服务器
cd SWMM-MCP
uv run swmm-controller.py5.Claude MCP设置示例
Claude Desktop / Web의 mcpSettings.json(또는 UI 설정 화면)에서 다음과 같이 등록
{
"mcpServers": {
"swmm-controller": {
"command": "uv",
"args": [
"--directory",
"C:/mcp/SWMM_mcp", // swmm-controller.py가 있는 폴더
"run",
"swmm-controller.py"
]
}
}
}
경로(C:/mcp/SWMM_mcp)는 본인 환경에 맞게 수정6.工具（工具）列表和简短说明
1）INP结构相关
list_nodes（项目路径：str）->列表\[str\] 返回指定项目的JUNCTION节点ID列表
list_links（项目路径：str）->列表\[str\] 返回CONDUIT链接ID列表
list_subcatches（项目路径：str）->列表\[str\] 返回SUBCATCHMENT ID列表
summarize_inp_basic（项目路径：str）->Dict\[str，int\]
n个接头、n个导管、n个子集水器반환
6.2.运行SWMM
run_swmm（项目路径：str，swmm_exe：可选\[str\]，超时：int）
启动SWMM引擎
消息、inp、rpt、out、stdout、stderr반환
未指定swmm_exe时使用环境变量SWMM_EXE或swmm5.exe
6.3.OUT时间序列查询
get_node_timeseries(project_path, node_id, variable="head", limit=200)
get_link_timeseries(project_path, link_id, variable="flow", limit=200)
get_subcatchment_timeseries(project_path, subcatchment_id, variable="runoff", limit=200)每个工具返回以下列表：
[
{ "step_index": 0, "time_label": "2020-01-01 00:00", "value": 0.0 },
{ "step_index": 1, "time_label": "2020-01-01 00:05", "value": 0.01 },
...
]6.4.OUT时间序列图（生成PNG）
plot_node_timeseries(project_path, node_id, variable="head", png_path=None, title=None, limit=0)
plot_link_timeseries(project_path, link_id, variable="flow", png_path=None, title=None, limit=0)图形由matplotlib创建，返回值为生成的PNG文件的完整路径。
6.5.RPT报告摘要
summarize_report(project_path, tail_lines=40)返回dict，包括错误/警告计数、代表性消息和最后N行。
6.6.导出外部连接
export_inp_to_geopackage(project_path, gpkg_path=None, crs="EPSG:5186") -> str将INP结构转换为GeoPackage后返回文件路径
直接从QGIS中加载，可以可视化网络结构
export_out_to_parquet(project_path, parquet_path=None) -> str将OUT的全部结果保存为Parquet文件并返回文件路径
pandas、PyTorch、可作为深度学习模型学习的输入数据