epanet-mcp-server
It exposes EPANET water-distribution modeling and simulation via MCP, letting an LLM manage, inspect, modify, simulate, and scenario-test networks.
Load/unload/list loaded or bundled networks and save modified
.inpfiles.Inspect summaries, nodes, links, patterns, controls, curves, and simulation options.
Run hydraulic, water-quality, and full simulations; query pressure/flow at specific times.
Modify nodes and links: junction demands, tanks, reservoirs, pipes, pumps, and valves.
Add/update patterns and simple controls.
Configure simulation duration, hydraulic/pattern/quality timesteps, and quality type.
Create what-if scenarios for demand changes, leaks, contamination, pressure changes, pump/valve controls, and multi-failure events.
Keep original networks unchanged by running scenarios on cloned sessions and returning lineage/change manifests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@epanet-mcp-server Load Net1.inp and show me a network summary."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
EPANET MCP Server
A Model Context Protocol (MCP) server that exposes EPANET water-distribution network modelling capabilities through ePyT - the EPANET Python Toolkit.
Any MCP-compatible LLM can load water network models, run simulations, modify parameters, and generate complex what-if scenarios through natural language.
This project is mainly developed and maintained by EURECAT.
Features
Tool Group | Tools | Description |
Network Management |
| Manage the lifecycle of EPANET network models, including loading, unloading, discovering available networks, and saving changes to disk. |
Network Inspection |
| Retrieve network topology, components, properties, controls, patterns, curves, and simulation settings without modifying the model. |
Simulation |
| Execute hydraulic and water-quality simulations and retrieve simulation results such as pressure and flow at specific times. |
Node Modification |
| Modify node-level properties, including junction demands, tank parameters, and reservoir hydraulic heads. |
Link Modification |
| Modify pipe, pump, and valve characteristics, including dimensions, operational status, speed, and control settings. |
Patterns & Controls |
| Manage time-dependent patterns and operational controls governing network behavior. |
Simulation Configuration |
| Configure simulation duration, time steps, and water-quality analysis options. |
Scenario Management |
| Generate what-if scenarios involving demand changes, leaks, contamination, pressure changes, operational adjustments, and multiple simultaneous failures. |
Related MCP server: idfkit-mcp
Requirements
pip install epyt mcpInstallation
git clone https://github.com/Applied-Artificial-Intelligence-Eurecat/epanet-mcp-server.git
cd epanet-mcp-server
pip install -e .Running the server
stdio (for Claude Desktop / Claude Code)
epanet-mcp-server
# or
python -m epanet_mcp.serverSSE / HTTP
epanet-mcp-server --transport sse --port 8000Claude Desktop configuration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or the equivalent on your platform:
{
"mcpServers": {
"epanet": {
"command": "uvx",
"args": [
"epanet-mcp-server"
]
}
}
}or
{
"mcpServers": {
"epanet": {
"command": "epanet-mcp-server",
"args": []
}
}
}If not on PATH:
{
"mcpServers": {
"epanet": {
"command": "python",
"args": [
"-m",
"epanet_mcp.server"
],
"cwd": "/path/to/epanet-mcp-server/src"
}
}
}Claude Code (.mcp.json)
Place this in the root of your project or ~/.claude/:
{
"mcpServers": {
"epanet": {
"command": "uvx",
"args": [
"epanet-mcp-server"
]
}
}
}or
{
"mcpServers": {
"epanet": {
"command": "epanet-mcp-server",
"args": []
}
}
}Example interactions
Once the server is connected, you can ask things like:
"Load Net1.inp and show me a summary of the network."
"Run a full simulation and tell me which node has the lowest pressure at hour 12."
"Double the base demand at junction 11 and re-run the simulation. How does pressure change?"
"Simulate a burst on pipe 10 with a 20% leakage fraction."
"Inject 10 mg/L of chlorine at node 11 between hours 1 and 3 and show me the contamination spread."
"What happens to pressures if the reservoir head drops from 150 m to 120 m?"
"Schedule Pump 9 to start at 06:00 and stop at 22:00."
"Close pipes 10 and 11 and the pump simultaneously. Where are service disruptions?"
Architecture
src/epanet_mcp/
├── server.py # FastMCP server – tool registration + entry point
├── session.py # Session leases, lifecycle states, registry ownership
├── utils.py # numpy → Python serialisation helpers
├── application/
│ └── scenario_service.py # Transactional scenario publication
├── domain/
│ ├── scenario.py # Scenario lineage and change manifests
│ └── validation.py # Shared physical and identifier validation
├── engine/
│ └── runner.py # Isolated, serialized EPANET solver workspaces
└── tools/
├── inspection.py # load / inspect network models
├── simulation.py # run hydraulic & quality simulations
├── modification.py# in-memory parameter changes
└── scenarios.py # what-if scenario generators (clone + modify + run)Session model: Each loaded network lives in a named session. Every ePyT operation holds an exclusive lease on that session, so unload and replacement wait for in-flight work before disposing the project handle. Loading a network with an existing ID constructs the replacement first and swaps it atomically.
Scenario tools clone the source into a private candidate. The candidate is only published after all modifications and any requested simulation succeed; failed scenarios are unloaded automatically. Explicit scenario-ID collisions are rejected, while omitted IDs receive a collision-resistant suffix.
Changes made through modification tools remain in the loaded in-memory session
and are included in later simulations. unload_network discards that session;
call save_network first when the modified model must persist on disk.
Simulation model: Editable sessions use persistent project handles, but each simulation is run from a fresh input-file snapshot on a separate solver handle. This prevents transient solver state from leaking into later operations. Because ePyT currently creates intermediate files relative to the process working directory, directory-changing solver calls are serialized and run in temporary workspaces that are always restored and removed.
Scenario results include lineage and a machine-readable change manifest. Leak
emitters are calibrated from a requested target flow and reference pressure (or
from a baseline flow fraction), and contamination intervals use the model's
pattern timestep. Injection boundaries must align with that timestep; use
set_pattern_timestep when finer scheduling is required.
Running the tests
pip install pytest
pytest tests/ -vBundled networks
ePyT ships with many standard benchmark networks including Net1, Net2, L-TOWN,
Hanoi, Anytown, Balerma and others. Use list_bundled_networks to discover
them all.
Contributing
Contributions are welcome, including bug reports, feature ideas, documentation, and code. To get started:
Check the open issues or open a new one to discuss your proposed change.
For code changes, fork the repository and create a branch from
main.Run
python -m pytest tests/ -v, then open a pull request againstmainthat links the issue and explains your change.
See CONTRIBUTING.md for the full contribution and review guidelines.
Citation
@software{AlasCercos2026EPANETMCP,
author = {Alàs, Oriol and Echeverria, Lluís and Palacín, Ian and Viñes, Oriol},
email = {oriol.alas@eurecat.org, lluis.echeverria@eurecat.org, ian.palacin@eurecat.org, oriol.vines.eurecat.org},
title = {{EPANET-MCP}: A Model Context Protocol Server for
Water Distribution Network Modeling and Simulation},
year = {2026},
version = {1.0.2},
organization = {Eurecat},
url = {https://github.com/Applied-Artificial-Intelligence-Eurecat/epanet-mcp-server},
note = {Open-source software, MIT License}
}License
MIT
Available Tools
45 toolsadd_controlB
Add a new simple control rule.
Example control strings::
"LINK P1 CLOSED IF NODE T1 ABOVE 20"
"LINK P1 OPEN IF NODE J2 BELOW 10"
"LINK Pump9 1.5 AT TIME 16:00"Args: network_id: Session id. control_string: EPANET simple-control syntax string.
Inputs: network_id (required), control_string (required). Returns: result
add_patternB
Add a new demand / operational pattern to the network.
Args: network_id: Session id. pattern_id: Unique name for the new pattern. values: Multiplier values for consecutive pattern time steps.
Inputs: values (required), network_id (required), pattern_id (required). Returns: result
create_contamination_eventA
Inject a contaminant at a node for a specified time window and simulate.
A clone of the source network is created. Quality type is set to CHEM automatically.
Args:
network_id: Source network id.
source_node_id: Node where the contaminant is introduced.
concentration: Concentration in mg/L (or model quality units).
start_time_s: Injection start time in seconds.
end_time_s: Injection end time in seconds.
source_type: "CONCEN", "MASS", "FLOWPACED", or
"SETPOINT".
scenario_id: Id for the cloned scenario session.
run_simulation: Run a full simulation after applying changes.
chemical_name: Chemical species name.
units: Chemical quality units.
Inputs: end_time_s (required), network_id (required), start_time_s (required), concentration (required), +6 more. Returns: result
create_demand_perturbationA
Apply base-demand multipliers to a set of nodes and optionally simulate.
A clone of the source network is created; the original is unchanged.
Args:
network_id: Source network id.
node_demands: {node_id: multiplier} — e.g. {"J1": 2.0}
doubles demand at J1.
scenario_id: Id for the cloned scenario session (auto-generated if
omitted).
run_simulation: Run a full simulation after applying changes.
Inputs: network_id (required), node_demands (required), scenario_id, run_simulation. Returns: result
create_leakage_eventA
Simulate a pipe burst by adding a leakage emitter at the pipe midpoint.
A clone of the source network is created; the original is unchanged. The burst pipe is split into two halves and a midpoint junction node with an emitter is added.
Args: network_id: Source network id. pipe_id: Id of the pipe that bursts. leak_fraction: Optional fraction of baseline mean pipe flow (0.0–1.0). scenario_id: Id for the cloned scenario session. run_simulation: Run a full simulation after applying changes. target_leak_flow: Optional target flow in the model's flow units. reference_pressure: Pressure at which the target flow applies. emitter_exponent: Pressure exponent; defaults to the model option.
Inputs: pipe_id (required), network_id (required), scenario_id, leak_fraction, +4 more. Returns: result
create_multi_failure_scenarioA
Simulate simultaneous pipe and/or pump failures (closure).
A clone of the source network is created; the original is unchanged.
Args: network_id: Source network id. failed_pipes: List of pipe ids to close. failed_pumps: List of pump ids to close. scenario_id: Id for the cloned scenario session. run_simulation: Run a full simulation after applying changes.
Inputs: network_id (required), scenario_id, failed_pipes, failed_pumps, +1 more. Returns: result
create_pressure_change_scenarioA
Study pressure changes by modifying reservoir heads.
A clone of the source network is created; the original is unchanged.
Args:
network_id: Source network id.
reservoir_heads: {reservoir_id: new_head} — e.g.
{"Reservoir1": 120.0}.
scenario_id: Id for the cloned scenario session.
run_simulation: Run a full simulation after applying changes.
Inputs: network_id (required), reservoir_heads (required), scenario_id, run_simulation. Returns: result
create_pump_control_scenarioA
Apply a time-based pump on/off or speed schedule and simulate.
A clone of the source network is created; the original is unchanged.
Each pump entry maps to a list of EPANET simple-control strings::
{
"Pump9": [
"LINK Pump9 1.0 AT TIME 06:00",
"LINK Pump9 CLOSED AT TIME 22:00"
]
}Args:
network_id: Source network id.
pump_schedule: {pump_id: [control_string, ...]} schedule.
scenario_id: Id for the cloned scenario session.
run_simulation: Run a full simulation after applying changes.
Inputs: network_id (required), pump_schedule (required), scenario_id, run_simulation. Returns: result
create_valve_control_scenarioA
Apply static valve-setting changes and simulate.
A clone of the source network is created; the original is unchanged.
Args:
network_id: Source network id.
valve_settings: {valve_id: new_setting} map.
scenario_id: Id for the cloned scenario session.
run_simulation: Run a full simulation after applying changes.
Inputs: network_id (required), valve_settings (required), scenario_id, run_simulation. Returns: result
delete_controlA
Delete a simple control by its 1-based index.
Args:
network_id: Session id.
control_index: 1-based index (use get_controls to list them).
Inputs: network_id (required), control_index (required). Returns: result
get_controlsC
Return all simple controls defined in the network.
Args: network_id: Session id of the network to inspect.
Inputs: network_id (required). Returns: result
get_curvesA
Return all curves (pump head, efficiency, volume, valve) in the network.
Args: network_id: Session id of the network to inspect.
Inputs: network_id (required). Returns: result
get_flow_at_timeA
Return link flows at (or nearest to) a specific simulation time.
Args: network_id: Session id of the network. time_s: Simulation time in seconds.
Inputs: time_s (required), network_id (required). Returns: result
get_linksA
Return all links (pipes, pumps, valves) with their attributes.
Attributes include type, connected nodes, diameter, length, roughness coefficient, and minor loss coefficient.
Args: network_id: Session id of the network to inspect.
Inputs: network_id (required). Returns: result
get_network_summaryA
Return a high-level summary of a loaded network.
Includes node/link counts, flow units, simulation duration and hydraulic timestep.
Args: network_id: Session id of the network to inspect.
Inputs: network_id (required). Returns: result
get_nodesA
Return all nodes (junctions, tanks, reservoirs) with their attributes.
Attributes include elevation, base demand, and type. Tanks also include min/max/initial water levels and diameter.
Args: network_id: Session id of the network to inspect.
Inputs: network_id (required). Returns: result
get_optionsA
Return simulation options: timesteps, units, quality settings, head-loss formula, and demand model.
Args: network_id: Session id of the network to inspect.
Inputs: network_id (required). Returns: result
get_patternsA
Return all demand / operational patterns defined in the network.
Args: network_id: Session id of the network to inspect.
Inputs: network_id (required). Returns: result
get_pressure_at_timeA
Return node pressures at (or nearest to) a specific simulation time.
Args: network_id: Session id of the network. time_s: Simulation time in seconds (e.g. 3600 = 1 hour).
Inputs: time_s (required), network_id (required). Returns: result
list_bundled_networksA
List every .inp example file bundled with ePyT (usable with load_network).
Inputs: no named parameters. Returns: result
list_networksA
Return the ids of all currently loaded networks.
Inputs: no named parameters. Returns: result
load_networkA
Load an EPANET .inp file into a named session.
Args:
path: Absolute file path, relative path, or bare filename
(e.g. "Net1.inp") searched in ePyT's bundled networks.
network_id: Optional human-readable session identifier.
Defaults to the file's base name without extension.
Returns:
network_id, path, and a network summary (node/link counts,
flow units, simulation duration).
Inputs: path (required), network_id. Returns: result
run_full_simulationA
Run both hydraulic and water-quality simulations and return combined time-series results (pressures, flows, quality, reaction rates, etc.).
Args: network_id: Session id of the network to simulate.
Inputs: network_id (required). Returns: result
run_hydraulic_simulationC
Run a full hydraulic simulation and return time-series results.
Returns pressures, demands, heads, flows, velocities, head-losses and link statuses at every reporting time step.
Args: network_id: Session id of the network to simulate.
Inputs: network_id (required). Returns: result
run_quality_simulationB
Run a full water-quality simulation and return time-series results.
Includes node/link quality concentrations plus all hydraulic results.
Configure the quality type first with set_quality_type.
Args: network_id: Session id of the network to simulate.
Inputs: network_id (required). Returns: result
save_networkB
Save the current (possibly modified) network to a new .inp file.
Args:
network_id: Session id of the network to save.
output_path: Destination file path (should end in .inp).
Inputs: network_id (required), output_path (required). Returns: result
set_hydraulic_timestepC
Set the hydraulic time step.
Args: network_id: Session id. timestep_s: Hydraulic time step in seconds.
Inputs: network_id (required), timestep_s (required). Returns: result
set_node_base_demandB
Set the base demand for a junction node.
Args: network_id: Session id. node_id: Junction node name/ID. demand: New base demand in the network's flow units. demand_category: Demand category index (default 1).
Inputs: demand (required), node_id (required), network_id (required), demand_category. Returns: result
set_patternB
Overwrite all multiplier values for a named demand pattern.
Args: network_id: Session id. pattern_id: Name of an existing pattern. values: New list of multiplier values.
Inputs: values (required), network_id (required), pattern_id (required). Returns: result
set_pattern_timestepC
Set the demand and quality-source pattern timestep in seconds.
Inputs: network_id (required), timestep_s (required). Returns: result
set_pipe_diameterA
Set the diameter of a pipe.
Args: network_id: Session id. pipe_id: Pipe name/ID. diameter: New diameter in the network's length units (mm or inches).
Inputs: pipe_id (required), diameter (required), network_id (required). Returns: result
set_pipe_lengthB
Set the length of a pipe.
Args: network_id: Session id. pipe_id: Pipe name/ID. length: New length in the network's length units (feet or metres).
Inputs: length (required), pipe_id (required), network_id (required). Returns: result
set_pipe_roughnessA
Set the roughness coefficient of a pipe.
Args: network_id: Session id. pipe_id: Pipe name/ID. roughness: Hazen-Williams C factor (or Darcy-Weisbach roughness height).
Inputs: pipe_id (required), roughness (required), network_id (required). Returns: result
set_pipe_statusB
Open or close a pipe.
Args:
network_id: Session id.
pipe_id: Pipe name/ID.
status: "OPEN" or "CLOSED".
Inputs: status (required), pipe_id (required), network_id (required). Returns: result
set_pump_head_curveB
Set (replace) the head-flow curve of a pump.
Args: network_id: Session id. pump_id: Pump link name/ID. flow_values: X-axis (flow) values. head_values: Y-axis (head) values.
Inputs: pump_id (required), network_id (required), flow_values (required), head_values (required). Returns: result
set_pump_speedC
Set the relative speed setting of a pump.
Args: network_id: Session id. pump_id: Pump link name/ID. speed: Speed ratio (1.0 = design speed, 0.5 = half speed).
Inputs: speed (required), pump_id (required), network_id (required). Returns: result
set_pump_statusA
Start or stop a pump.
Args:
network_id: Session id.
pump_id: Pump link name/ID.
status: "OPEN" (running) or "CLOSED" (stopped).
Inputs: status (required), pump_id (required), network_id (required). Returns: result
set_quality_timestepA
Set the water-quality simulation time step.
Args: network_id: Session id. timestep_s: Quality time step in seconds.
Inputs: network_id (required), timestep_s (required). Returns: result
set_quality_typeA
Set the water-quality analysis type.
Args:
network_id: Session id.
quality_type: One of "NONE", "AGE", "TRACE", or "CHEM".
tracer_node: Source node for TRACE analysis.
chemical_name: Species name for CHEM analysis.
units: Concentration units (e.g. "mg/L").
Inputs: network_id (required), quality_type (required), units, tracer_node, +1 more. Returns: result
set_reservoir_headA
Set the total head (water-surface elevation) of a reservoir.
Args: network_id: Session id. reservoir_id: Reservoir node name/ID. head: Total head value in the network's pressure-head units.
Inputs: head (required), network_id (required), reservoir_id (required). Returns: result
set_simulation_durationC
Set the total simulation duration.
Args: network_id: Session id. duration_s: Duration in seconds (e.g. 86400 = 24 h).
Inputs: duration_s (required), network_id (required). Returns: result
set_tank_parametersB
Update one or more parameters of a tank node.
Only provided parameters are changed; others retain their current values.
Args: network_id: Session id. tank_id: Tank node name/ID. initial_level: Water level at simulation start. min_level: Minimum operating level. max_level: Maximum operating level. diameter: Tank diameter.
Inputs: tank_id (required), network_id (required), diameter, max_level, +2 more. Returns: result
set_valve_settingA
Set the initial setting of a valve.
PRV/PSV/PBV → pressure setpoint; FCV → flow rate; TCV → loss coefficient.
Args: network_id: Session id. valve_id: Valve link name/ID. setting: New setting value.
Inputs: setting (required), valve_id (required), network_id (required). Returns: result
set_valve_statusB
Open or close a valve.
Args:
network_id: Session id.
valve_id: Valve link name/ID.
status: "OPEN" or "CLOSED".
Inputs: status (required), valve_id (required), network_id (required). Returns: result
unload_networkA
Unload a previously loaded network and free its resources.
Args:
network_id: The session id returned by load_network.
Inputs: network_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 45 tools
Tools split cleanly into getters, setters, simulation runners, and scenario creators, each targeting a distinct resource or action. A few boundaries blur, such as run_hydraulic_simulation vs run_full_simulation vs run_quality_simulation, and direct setters (set_pump_status) vs scenario wrappers (create_pump_control_scenario), but descriptions generally clarify the differences.
Every tool follows a predictable snake_case verb_noun pattern: list_, get_, set_, create_, run_, add_, delete_, load_, unload_, save_. No mixed conventions or vague verbs appear.
At 45 tools, the surface is well above the typical well-scoped range. Many granular setters and scenario creators could be consolidated (e.g., a generic set_link_attribute or parameterized scenario builder), making the set heavy for agents to navigate.
The surface covers loading, inspection, parameter modification, simulation, time queries, and several scenario types. However, there are no tools to add or delete network elements (junctions, pipes, pumps, valves, tanks), which is a notable gap for building or restructuring networks; scenario deletion is also absent.
Maintenance
Related MCP Connectors
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
SWAT+ watershed models for any river in the lower 48 states, with groundwater and PFAS data
AI-powered life cycle assessment and modelling: connect to LCA databases, build and analyze systems
Conversational what-if simulation: build, diagnose and compare Petri-net models; CC0 catalog.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that provides a toolbox for interacting with EPA SWMM stormwater models, enabling users to analyze model data and interpret results through LLM-driven tools. It assists stormwater modelers in understanding hydraulic systems and modeling behavior using natural language interfaces.188MIT

idfkit-mcpofficial
AlicenseAqualityBmaintenanceEnables AI assistants to create, edit, and simulate EnergyPlus building energy models via natural language. Supports schema exploration, model editing, simulation execution, and documentation search.3998 PyPI14MIT- AlicenseAqualityDmaintenanceEnables AI assistants to load, simulate, inspect, and edit EPANET hydraulic/water-quality models locally via stdio.33MIT
- AlicenseAqualityBmaintenanceEnables AI agents to design, connect, and simulate water-handling systems from tested physical component models, with typed tools and physics-based warnings.20Apache 2.0