EPANET MCP Server

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.

---

Features

---

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": "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": "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 # Thread-safe registry of open ePyT sessions ├── utils.py # numpy → Python serialisation helpers └── 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. Scenario tools automatically clone the source session into a new independent session so the baseline network is never mutated.

---

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.

---

License

MIT