Agentic SWMM
About
Eleven MCP servers for reproducible EPA SWMM stormwater modelling — building, simulation, calibration, GIS, climate scenarios, uncertainty, plotting, and modelling memory.
Details
- Author
- zhonghao1995
- Categories
- Other, Automation
Jump to
Setup
Install Agentic SWMM in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/zhonghao1995/agentic-swmm-workflow
Follow the installation instructions in the repository README, then restart your MCP client.
Pre-1.0· stablev0.9.3·pip install aiswmm==0.9.3·CHANGELOG
[!TIP]Headaches from tedious model setup?Try our another projectSWMMCanada, our automated model-building project: draw an area anywhere in Canada and get a ready-to-run SWMM model. Up and running now.
- Agentic SWMM for reproducible stormwater modeling:theaiswmmruntime + Skills + MCP + SWMM, with a verification-first workflow and Obsidian-compatible audit trail.
- Five minutes, one command:an Agentic SWMM workflow that is auditable, memory-informed, and agent-ready.
- Live demo (no install, offline case replay):try it in the browser ataiswmm.com.
- Case study, a model that said not to trust it:the same Victoria AOI against the real municipal network on a Windows 11 ARM laptop, where the requested week turned out to be dry: the run reported a 6.111% routing continuity error and a flooding volume against zero rainfall, named both as disqualifying, and proposed the design storm that would settle it, incases/downtown-victoria-on-arm.md.
- Case study, one prompt to client deliverable:a single English sentence fetched the real downtown Victoria, BC municipal storm network (423 subcatchments), ran SWMM, audited it, screened it against the design rulebook, plotted the hydrograph, and exported a Word report with the figures embedded; the exact prompt, the numbers, and every artifact are incases/downtown-victoria.
- SWMMCanadaupstream, ready to use:inside Canada, real municipal storm networks for 35 cities or synthesis anywhere else in the country, built from Canadian open data and fetched directly into aiswmm through thefetch_swmm_from_canadatool; outside Canada,SWMManywhere-based synthesis covers the rest of the globe. Two complementary upstream sources, and one goal can chain fetch, simulate, and audit into a single run folder.
- Bring the LLM you already pay for:ten provider routes behind one detect-firstaiswmm setupwizard (OpenAI, Anthropic, OpenRouter, DeepSeek, Groq, Gemini, local Ollama and LM Studio, OpenAI-compatible gateways, custom endpoints), with an optional local fallback chain that keeps sessions alive through outages and quota windows.
- Calibrate, then force:aiswmm climatebatches precipitation-scaled climate scenarios over a calibrated model and writes a per-scenario comparison of runoff, flooding, outflow, and peak flow.
- A domain-specific agent runtime, managed-agent style:every session is self-describing (verbatim goal, auto-derived agent snapshot with tool/skill/prompt hashes, environment fingerprint, append-only event log, status lifecycle), and the orchestration plus verification rules are open source and auditable.
- Runtime-portable:the Skills and MCP servers also work withCodex,OpenClaw, andHermes Agent.
- Published research:our paper is published inAI for Engineering(MDPI), June 9, 2026:read the paper.
Agentic SWMM is an open-source, verification-first framework for reproducible and extensible stormwater modelling, starting with EPA SWMM. It connects QGIS-based preprocessing, upstream model generation fromSWMMCanadainside Canada (real storm networks for 35 cities, synthesis anywhere else in the country) and SWMManywhere-based synthesis outside Canada, deterministic SWMM execution, QA checks, provenance tracking, calibration and climate-scenario support, documentation, and modelling memory, while keeping human modellers in control.
The goal is not to replace SWMM or the modeller, but to build an agentic modelling layer that makes stormwater-modelling workflows easier to reproduce, audit, extend, remember, and trust.Agentic SWMM comes with aiswmm as its built-in runtime. Users can describe a modelling goal in natural language, while model execution remains deterministic, inspectable, and artifact-based. The repository's MCP servers and Skills can also be used with other agent runtimes, including Codex, Claude, OpenClaw, and Hermes.
This is not a simple chat-to-SWMM wrapper. The aiswmm runtime can help coordinate the workflow, but model files, SWMM runs, QA checks, plots, provenance records, audit notes, and modelling memory remain visible as reusable artifacts. Modelling memory can summarize repeated problems and propose Skill refinements, but accepted changes still require human review and benchmark verification.
Authors:Zhonghao Zhang&Caterina Valeo
License:MIT
Stormwater modelling is rarely one command. A typical SWMM project can involve GIS preprocessing, rainfall formatting, parameter assignment, network assembly, INP construction, model execution, QA checks, plots, calibration, uncertainty analysis, and reporting.
Agentic SWMM provides a middle path: natural-language orchestration with deterministic SWMM execution, explicit provenance, project memory, and verification-first modelling.
- Quick onboarding:start from one-line macOS/Linux or Windows installers, with Docker and Python package paths documented separately.
- Agent-guided, SWMM-grounded:agents can coordinate tasks, while model execution stays deterministic, inspectable, and CLI-runnable.
- Modular skill layer:GIS, climate, building, running, plotting, calibration, uncertainty, audit, and orchestration are separated into reusable modules with MCP interfaces where available.
- Verification-first provenance:build, run, audit, and comparison stages emit traceable artifacts before outputs are treated as evidence.
- Supervised skill evolution:audited runs can surface recurring workflow patterns and propose updates to existing skills or new skills, while staying coupled to the current skill-driven framework.
curl -fsSL https://aiswmm.com/install.sh | bash
irm https://aiswmm.com/install.ps1 | iex
Reproducible run (pinned Docker image, v0.9.3), no local install:
docker run --rm -v "$PWD/runs:/app/runs" ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.9.3 acceptance
After installation, launch the runtime withaiswmm.
One-line installers run a remote script; review it first if you want to see what executes. When it finishes it hands over toaiswmm setup, which lists every route and detects what is already running; three of them need no API key at all, including a local gateway that fronts a ChatGPT plan. For storing a key directly, seeAPI key configuration. Never paste API keys into theaiswmmconversation.
Three ways in(one-line installer, Docker, orpip), compared side by side (what you get, prerequisites, reproducibility, when to pick each):choosing an install path. If something goes wrong, or you want a provider that needs no API key:[install and troubleshooting.
The workflow has three connected layers: execution, modeling memory, and controlled skill evolution. Natural-language requests can trigger reproducible SWMM actions; audited artifacts update human-readable and machine-readable memory; repeated patterns can produce skill-refinement proposals that still require human review and benchmark verification.
…
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
