AI导哈

SWMM模型控制服务器

SWMM-MCP是一个通过Model Context Protocol (MCP)控制EPA-SWMM模型并进行后处理的Python服务器，提供SWMM执行、结果提取、图形生成和数据导出功能。

  • by choym01691-netizen
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 choym01691-netizen/SWMM-Controller-MCP

使用说明

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 matplotlib

4.运行服务器


cd SWMM-MCP
uv run swmm-controller.py

5.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、可作为深度学习模型学习的输入数据

相关 MCP