This server provides tools to execute, parse, and compare EPA SWMM stormwater model runs programmatically.
Run SWMM simulations (swmm_run): Execute a SWMM5 model from an .inp file, writing output files (.rpt, .out) and a manifest.json into a specified run directory. Auto-detects the primary outfall node from the [OUTFALLS] section if not provided, and optionally records which modeling-memory entries were applied for full auditability.
Extract peak flow metrics (swmm_peak): Parse peak flow rate and time-of-peak for a specific node or outfall from a .rpt report file.
Parse continuity tables (swmm_continuity): Extract Runoff Quantity and Flow Routing continuity error tables from a .rpt file, supporting QA checks on mass balance and simulation integrity.
Compare two SWMM runs (swmm_compare): Compute and compare continuity error percentages between two .rpt files (e.g., GUI vs. CLI), useful for reproducibility and cross-environment validation.
Pre-1.0 · stable v0.9.3 ·
pip install aiswmm==0.9.3· CHANGELOG
Headaches from tedious model setup? Try our another project SWMMCanada, 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: the aiswmm runtime + Skills + MCP + SWMM, verification-first, with a full audit trail.
Live demo, no install: try it in the browser at aiswmm.com.
One prompt to client deliverable: one English sentence fetched the real downtown Victoria storm network, ran SWMM, audited it, and exported a Word report: cases/downtown-victoria.
A model that said not to trust it: when the requested week turned out dry, the run named its own errors as disqualifying instead of handing over bad numbers: cases/downtown-victoria-on-arm.md.
Real networks upstream: SWMMCanada covers 35 Canadian cities, SWMManywhere synthesis covers the rest of the globe.
Bring the LLM you already pay for: ten provider routes behind one aiswmm setup wizard, with a local fallback chain.
Published research: published in AI for Engineering (MDPI, 2026): read the paper.
Related MCP server: SciAgentKit
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 from SWMMCanada inside 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.
macOS and Linux:
curl -fsSL https://aiswmm.com/install.sh | bashWindows PowerShell:
irm https://aiswmm.com/install.ps1 | iexReproducible 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 acceptanceAfter installation, launch the runtime with aiswmm.
One-line installers run a remote script; review it first if you want to see what executes. When it finishes it hands over to aiswmm 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, see API key configuration. Never paste API keys into the aiswmm conversation.
Three ways in (one-line installer, Docker, or pip), 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.
generated or supplied SWMM input files such as model.inp
SWMM report and binary outputs such as .rpt and .out
manifests, command traces, QA summaries, and parsed peak-flow metrics
rainfall-runoff figures, calibration summaries, and fuzzy uncertainty summaries
audit records: experiment_provenance.json, comparison.json, and experiment_note.md
Obsidian-ready modelling notes and modelling-memory summaries
The repository includes runnable benchmarks and research previews with different evidence boundaries. The README keeps only the index; figures, commands, and boundary notes live in Validation evidence.
Path | What it shows | Evidence boundary |
QGIS-to-Agentic SWMM preprocessing using entropy and fuzzy-similarity concepts from Zhang & Valeo's Journal of Hydrology paper | GIS preprocessing concept, not a calibrated SWMM performance claim | |
Public TUFLOW GeoPackage layers converted into SWMM-ready artifacts, QA, and audit | Structured raw GIS path, not arbitrary CAD/GIS recognition | |
External 40-subcatchment Tecnopolo model execution, plotting, and direct | Prepared INP validation path | |
Tecnopolo HORTON parameter perturbation and hydrograph envelope preview | Prior uncertainty smoke, not calibration | |
Raw-like inputs extracted from a public SWMM fixture and rebuilt through the modular path | Adapter handoff check, not greenfield watershed generation | |
A natural-language prompt ( | SWMM execution-layer reproducibility, not agentic workflow reproducibility | |
LLM-driven dispatch + data-scarce urban modeling (SWMManywhere) | A single natural-language sentence referring only to a WGS84 bounding box drives the end-to-end SWMManywhere → SWMM → audit → network-map workflow on two independent regions (Greenwich Peninsula and NYC Midtown, ~1 km² each), with no shapefile, no DEM file, and no step-by-step tool instructions. Synthesis is the work of SWMManywhere (Imperial College London, BSD-3-Clause). | Agent-side plumbing for data-scarce baseline modeling; not a calibrated or validated network. Calibration is next-milestone scope. |
An 11-word user prompt drove a complete Tecnopolo run on 2026-05-28 during which the LLM autonomously queried | Memory layer fires correctly and shapes planner decisions; staleness weighting and negative-precedent handling are next-milestone scope. |
Examples: TUFLOW and Tecnopolo.
The audit layer consolidates artifacts, QA checks, and metric provenance into an Obsidian-compatible experiment note. This example catches a recorded peak-flow value that does not match the value re-parsed from the SWMM report source section.
The downstream modelling-memory layer can summarize audited run histories into recurring failure patterns, assumptions, missing evidence, QA issues, lessons learned, and controlled proposals for updating existing skills or creating new skills. Because skills drive the workflow, these proposals stay coupled to the current Agentic SWMM framework and still require human review and benchmark verification before acceptance.
More details: Experiment audit framework and Modeling memory and skill evolution.
Agentic SWMM is the SWMM engine within a larger effort toward a trustworthy, auditable, fully automated urban-hydrology modelling platform: a top-level agentic runtime orchestrating engine-specific automation on top of a shared data-to-model front end.
Project | Role in the ecosystem | Status |
Orchestration layer: top-level agentic runtime that governs data, model selection, runs, and audit across the engine branches | LSTM catchment-modelling pipeline live; cross-engine (SWMM / MIKE+) orchestration in progress | |
Data & model-building layer: ingests and cleans GIS / open data and synthesises reliable model files; the shared front end for the engines. Agentic SWMM consumes it as an upstream INP source via | SWMM today; extending to MIKE+ and InfoWorks ICM | |
Agentic SWMM (this repository) | SWMM engine: verification-first EPA SWMM automation (Skills + MCP + deterministic runs + audit) | Stable v0.9.3 |
MIKE+ engine: headless DHI MIKE+ automation (Skills + MCP), built on the Agentic SWMM design and the same method paper | Active development |
Beyond its own aiswmm runtime, the Agentic SWMM workflow can be driven by external agent runtimes: Codex, Claude Code, OpenClaw, or Hermes. For an agent-orchestrated run, preload the agent/memory/ package and point the runtime at the top-level entry skill skills/swmm-end-to-end/SKILL.md, which decides which workflow path to take, which QA gates must pass, and when to stop rather than invent missing inputs.
Install the skills into any skills-aware runtime (Claude Code, Codex, OpenCode, …) with one command:
npx skills add Zhonghao1995/agentic-swmm-workflowThe skills carry the workflow and evidence contracts; pair them with the project install for the executable toolchain (aiswmm CLI, SWMM solver, MCP servers).
More details: Codex runtime path · OpenClaw execution path · Skill installation · MCP runtime integration.
Validation evidence - benchmark scope, commands, audit example, and evidence boundaries
Installation and CLI guide - Docker, local install, Windows options, and CLI examples
Install and troubleshooting - the one-liner per platform, what goes wrong on a real machine and why, and which platforms are covered by an install job in CI
Two interfaces, one engine - how natural-language goals and CLI verbs map onto the same deterministic tools and artifacts, and when to use which
LLM provider routes - ten routes out of the box (OpenAI, Anthropic, OpenRouter, DeepSeek, Groq, Gemini, local Ollama/LM Studio, gateways, custom endpoints), the aiswmm setup wizard, per-route auth, and the local fallback chain
Climate scenario batches - aiswmm climate: calibrate first, then compare the model's response under precipitation-scaled climate scenarios, one canonical 03_climate/ summary per run
Experiment audit framework - provenance, comparison, and Obsidian note contracts
Modeling memory and skill evolution - controlled memory-to-skill refinement loop
Memory runtime - on-disk substrate, four confidence quadrants, and runtime opt-out flags
Memory runtime CLI examples - one worked example per memory verb
Codex runtime path - local development, audit, Obsidian, and evidence-review workflow
OpenClaw execution path - MCP tool-call sequence for agent runtimes
Repository map - folder-level walkthrough
Calibration example - compact calibration support example
Contributions are welcome in additional SWMM case studies, stronger calibration and validation workflows, DEM / land-use / soil / drainage-asset workflows, new MCP tools, QA testing, tutorials, and interoperability with GIS, ML, and hydrologic toolchains.
Contact:
GitHub citation metadata is provided in CITATION.cff. Please cite the published article.
Zhang, Z., & Valeo, C. (2026). Agentic SWMM: Auditable and reproducible stormwater modelling workflow with Agent Skills and Model Context Protocol. AI for Engineering, 1(1), 5. https://doi.org/10.3390/aieng1010005
Zhang, Z., & Valeo, C. (2026). agentic-swmm-workflow [Computer software]. GitHub. https://github.com/Zhonghao1995/agentic-swmm-workflow
Compare continuity error (%) between two SWMM .rpt files (e.g., GUI vs CLI).
| Name | Required | Description | Default |
|---|---|---|---|
| rpt | Yes | ||
| rpt2 | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose all behavioral traits. It states 'compare continuity error (%)' but does not explain what the comparison entails (e.g., subtraction, percentage difference), whether the files are read or modified, or any side effects. This is insufficient for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, but it lacks necessary details. It is front-loaded with the action and resource, but the brevity comes at the cost of completeness. A longer description with parameter mapping and output info would be more useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and two required parameters, the description should explain what the tool returns (e.g., difference in continuity error) and clarify the role of each parameter. The current description does not provide enough context for an agent to use the tool correctly, especially when sibling tools exist but are not differentiated beyond basic purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so parameters have no descriptions. The tool description mentions 'two SWMM .rpt files' but does not map them to the parameters 'rpt' and 'rpt2'. The parameter names themselves are ambiguous (could be file paths or content). The example 'GUI vs CLI' does not clarify which parameter is which. This leaves the agent without enough information to correctly assign file paths.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'Compare', the resource 'continuity error (%)', and the files 'SWMM .rpt files', with an example 'GUI vs CLI'. It effectively distinguishes from sibling tools like swmm_continuity (one file) and swmm_peak (peaks) by focusing on comparison of two files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning 'two SWMM .rpt files' and the example 'GUI vs CLI', but it does not explicitly state when to use this tool versus alternatives (e.g., when comparing consistency) or when not to use it. No exclusions or alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse Runoff Quantity / Flow Routing continuity tables from a SWMM .rpt.
| Name | Required | Description | Default |
|---|---|---|---|
| rpt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It only states the action (parse) without revealing side effects, error conditions, or performance implications. The agent cannot know if the operation is read-only, what happens on missing data, or any authentication needs. The minimal description leaves significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the verb. However, it omits critical parameter semantics, which makes it less effective despite its brevity. A conciseness score of 3 reflects that it is not wasteful but fails to deliver essential information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter with 0% schema coverage, no annotations, and no output schema, the description is severely incomplete. It fails to specify the parameter's meaning, return format, or edge cases. The agent lacks sufficient information to invoke the tool correctly without external knowledge of SWMM .rpt files.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining the 'rpt' parameter. The description mentions 'SWMM .rpt' but does not clarify whether the parameter expects a file path, file content, or a reference. The agent cannot infer the expected format (string could be path, base64, or raw text) from the description alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: parsing Runoff Quantity and Flow Routing continuity tables from a SWMM .rpt file. The verb 'Parse' combined with the specific resource 'continuity tables' makes the purpose unambiguous. It distinguishes itself from sibling tools (swmm_compare, swmm_peak, swmm_run) which handle different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description only explains what the tool does, without mentioning prerequisites, context, or scenarios where this tool is preferred over siblings. Without such guidance, the agent must infer usage from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse peak flow and time-of-peak for a specific node/outfall from a SWMM .rpt. The node name must be supplied (no default).
| Name | Required | Description | Default |
|---|---|---|---|
| rpt | Yes | ||
| node | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states the tool parses from a .rpt file, but does not reveal error behavior (e.g., node not found), whether it modifies files, or required file structure. Critical missing details for a parse tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at two sentences, front-loaded with the main action. Every word adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parse tool with 2 parameters and no output schema, the description is adequate but could include details on expected .rpt format (e.g., SWMM 5 output) or behavior on missing node. It covers essentials but lacks robustness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning: 'rpt' is the SWMM .rpt file, 'node' is the node/outfall name, and it must be supplied. This clarifies the purpose beyond the bare parameter names, though format or constraints are not specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states that the tool parses peak flow and time-of-peak from a SWMM .rpt file for a specific node/outfall. It is clear and specific, but does not differentiate from sibling tools like swmm_compare or swmm_run beyond the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that the node name must be supplied, but provides no guidance on when to use this tool vs alternatives (e.g., swmm_run for simulation, swmm_compare for comparisons) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run swmm5 on an INP and write rpt/out + manifest.json into runDir. When 'node' is omitted, auto-detect the first entry of the .inp [OUTFALLS] section so the manifest's peak metric targets the real outfall.
| Name | Required | Description | Default |
|---|---|---|---|
| inp | Yes | ||
| node | No | Optional. If omitted, the first [OUTFALLS] entry of the .inp is used. | |
| runDir | Yes | ||
| outName | No | ||
| rptName | No | ||
| memoriesApplied | No | Optional. List of modeling-memory entry ids whose parameters were programmatically applied to this run's inputs (e.g. ["cm-abc123"]). Recorded in manifest.json under 'memories_applied' for auditability. Omit when no memory was applied. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses writing output files and auto-detecting outfall node when omitted, but lacks detail on side effects like file overwriting, error handling, or runtime. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the primary action and adding key auto-detection detail. Every word is purposeful, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity, no output schema, and no annotations, the description omits important context such as return value format, error conditions, typical runtime, and details about output file structure. It is insufficient for fully understanding tool behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (33%), so description must compensate. It explains the 'node' parameter's auto-detection behavior and mentions 'inp' and 'runDir' by context. However, parameters like 'rptName' and 'outName' are not described beyond their presence in file names, leaving some semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs swmm5 on an INP file and writes output files into runDir. It mentions specific outputs (rpt, out, manifest.json) and distinguishes from siblings like swmm_compare, swmm_continuity, and swmm_peak by focusing on simulation execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for running a simulation but does not explicitly state when to use this tool versus its siblings. No guidance on prerequisites or when not to use it is provided, though the sibling names offer indirect context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.7.3swmm_compareswmm_continuityswmm_peakswmm_runEach tool targets a distinct SWMM task: comparing reports, parsing continuity tables, extracting peak flows, and running simulations. No overlap or confusion.
All tools follow a consistent 'swmm_<verb>' pattern, making them predictable and easy to differentiate.
Four tools is reasonable for a focused SWMM analysis server, covering key operations without unnecessary clutter.
Covers core workflows (run, compare, parse continuity and peaks). Minor gaps like editing input files or exporting results are acceptable for this scope.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP gateway federating 21 biomedical MCP servers behind one endpoint: gnomAD, ClinVar, HPO, VEP.
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
Workflow diagnostics, capability routing, and x402 settlement for MCP-compatible agents.
Built-environment forecasts, public benchmarks, and permit or zoning readiness through remote MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Zhonghao1995/agentic-swmm-workflow'
If you have feedback or need assistance with the MCP directory API, please join our Discord server