Skip to main content
Glama

EPANET MCP Server

License: MIT Linter Pytest PyPI version Total Downloads MCP Registry

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

load_network, unload_network, list_networks, list_bundled_networks, save_network

Manage the lifecycle of EPANET network models, including loading, unloading, discovering available networks, and saving changes to disk.

Network Inspection

get_network_summary, get_nodes, get_links, get_patterns, get_controls, get_curves, get_options

Retrieve network topology, components, properties, controls, patterns, curves, and simulation settings without modifying the model.

Simulation

run_hydraulic_simulation, run_quality_simulation, run_full_simulation, get_pressure_at_time, get_flow_at_time

Execute hydraulic and water-quality simulations and retrieve simulation results such as pressure and flow at specific times.

Node Modification

set_node_base_demand, set_tank_parameters, set_reservoir_head

Modify node-level properties, including junction demands, tank parameters, and reservoir hydraulic heads.

Link Modification

set_pipe_diameter, set_pipe_roughness, set_pipe_status, set_pipe_length, set_pump_status, set_pump_speed, set_pump_head_curve, set_valve_setting, set_valve_status

Modify pipe, pump, and valve characteristics, including dimensions, operational status, speed, and control settings.

Patterns & Controls

set_pattern, add_pattern, add_control, delete_control

Manage time-dependent patterns and operational controls governing network behavior.

Simulation Configuration

set_simulation_duration, set_hydraulic_timestep, set_pattern_timestep, set_quality_timestep, set_quality_type

Configure simulation duration, time steps, and water-quality analysis options.

Scenario Management

create_demand_perturbation, create_leakage_event, create_contamination_event, create_pressure_change_scenario, create_pump_control_scenario, create_valve_control_scenario, create_multi_failure_scenario

Generate what-if scenarios involving demand changes, leaks, contamination, pressure changes, operational adjustments, and multiple simultaneous failures.


Related MCP server: idfkit-mcp

Requirements

  • Python ≥ 3.10

  • ePyT ≥ 2.0

  • mcp ≥ 1.0

pip install epyt mcp

Installation

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.server

SSE / HTTP

epanet-mcp-server --transport sse --port 8000

Claude 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/ -v

Bundled 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:

  1. Check the open issues or open a new one to discuss your proposed change.

  2. For code changes, fork the repository and create a branch from main.

  3. Run python -m pytest tests/ -v, then open a pull request against main that 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 tools
add_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_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

    B3.3/5.0

    Scored across 45 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An 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.
      18
      8
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to create, edit, and simulate EnergyPlus building energy models via natural language. Supports schema exploration, model editing, simulation execution, and documentation search.
      39
      98 PyPI
      14
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to load, simulate, inspect, and edit EPANET hydraulic/water-quality models locally via stdio.
      33
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to design, connect, and simulate water-handling systems from tested physical component models, with typed tools and physics-based warnings.
      20
      Apache 2.0