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