Skip to main content
Glama
README.md
# EPANET MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Applied-Artificial-Intelligence-Eurecat/epanet-mcp-server/blob/main/LICENSE)
[![Linter](https://github.com/Applied-Artificial-Intelligence-Eurecat/epanet-mcp-server/actions/workflows/linter.yml/badge.svg?branch=main)](https://github.com/Applied-Artificial-Intelligence-Eurecat/epanet-mcp-server/actions/workflows/linter.yml)
[![Pytest](https://github.com/Applied-Artificial-Intelligence-Eurecat/epanet-mcp-server/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/Applied-Artificial-Intelligence-Eurecat/epanet-mcp-server/actions/workflows/test.yml)
[![PyPI version](https://img.shields.io/pypi/v/epanet-mcp-server.svg?label=PyPI)](https://pypi.org/project/epanet-mcp-server/)
[![Total Downloads](https://img.shields.io/pepy/dt/epanet-mcp-server?label=total%20downloads)](https://pepy.tech/projects/epanet-mcp-server)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-blue.svg)](https://registry.modelcontextprotocol.io/?q=io.github.Applied-Artificial-Intelligence-Eurecat%2Fepanet-mcp-server)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes EPANET water-distribution network
modelling capabilities through [ePyT](https://github.com/KIOS-Research/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. |

---

## Requirements

- Python ≥ 3.10
- [ePyT](https://pypi.org/project/epyt/) ≥ 2.0
- [mcp](https://pypi.org/project/mcp/) ≥ 1.0

```bash
pip install epyt mcp
```

---

## Installation

```bash
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)

```bash
epanet-mcp-server
# or
python -m epanet_mcp.server
```

### SSE / HTTP

```bash
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:

```json
{
  "mcpServers": {
    "epanet": {
      "command": "uvx",
      "args": [
        "epanet-mcp-server"
      ]
    }
  }
}
```

or

```json
{
  "mcpServers": {
    "epanet": {
      "command": "epanet-mcp-server",
      "args": []
    }
  }
}
```

If not on `PATH`:

```json
{
  "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/`:

```json
{
  "mcpServers": {
    "epanet": {
      "command": "uvx",
      "args": [
        "epanet-mcp-server"
      ]
    }
  }
}
```

or

```json
{
  "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

```bash
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](https://github.com/Applied-Artificial-Intelligence-Eurecat/epanet-mcp-server/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](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

<!-- mcp-name: io.github.Applied-Artificial-Intelligence-Eurecat/epanet-mcp-server -->

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