EPANET MCP Server

An MCP server that puts the EPANET hydraulic/water-quality engine in front of AI assistants (Claude Desktop, Cursor, VS Code Copilot, Claude Code, …) over stdio — no cloud round-trip, no browser.

It lets an AI assistant load an EPANET .inp/.net model, inspect it, run simulations, read per-node/per-link results, and make validated edits, all locally.

Tools

• Network I/O — load_network, save_network, list_networks
• Inspection — get_network_summary, get_nodes, get_links, get_coordinates
• Simulation — run_simulation, get_node_results, get_link_results
• Mutation (engine-validated, results-invalidating) — set_pipe_diameter, set_junction_demand, set_pump_speed, set_valve_setting, set_node_elevation, set_demand_pattern, add_tank, remove_tank, add_valve
• Model building — create_network, assign_demands, sample_elevations, fetch_road_network, generate_network_from_bbox
• Design helpers — lookup_pipe_diameters, recommend_diameter, friction_loss, calculate_minor_loss, pipe_sizing_wizard, pump_selection, list_fitting_kfactors
• Optimization — optimize_network, run_candidate

generate_network_from_bbox auto-lays out a junction/pipe skeleton from real OpenStreetMap road data for a bounding box, with a reservoir placed at the nearest waterway and ground elevations sampled from a bundled IFSAR 10 m DEM.

Prerequisites

Requirement	Version
Node.js	20.x or 21.x
OS	Windows, macOS, or Linux — transport is stdio, no network ports opened

Install

npm install

Run locally

The data directory the server reads from (load_network) and writes to (save_network) is path-contained — the server refuses any file outside it.

mkdir -p data
cp your-model.inp data/
export EPANET_DATA_DIR=$(pwd)/data
npm start

The server boots and waits for a client on stdio.

Wire it to an AI app

Claude Desktop

Edit claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "epanet": {
      "command": "npm",
      "args": ["start"],
      "cwd": "<absolute path to this repo>",
      "env": {
        "EPANET_DATA_DIR": "<absolute path to this repo>/data"
      }
    }
  }
}

Cursor / VS Code

Same shape works in Cursor (%APPDATA%\Cursor\User\globalStorage\mcp.json) or VS Code (%APPDATA%\Code\User\mcp.json) — command: "npm", same args/env.

Configuration

The server reads these environment variables:

Env var	Default	Purpose
EPANET_DATA_DIR	cwd	Folder load_network/save_network may read/write
EPANET_DEM_DIR	unset	Folder the DEM/elevation tools read from
EPANET_AUTH_PUBLIC_KEY	unset	RS256 public key for optional token-mode auth
EPANET_AUTH_VALIDATE_URL	unset	Loopback URL for token validation
EPANET_AUTH_ISSUER	unset	Expected JWT iss
EPANET_AUTH_AUDIENCE	unset	Expected JWT aud
EPANET_AUTH_TOKEN	unset	Static bearer token (CI use)
EPANET_AUTH_TOKEN_FILE	unset	Path to a file containing the bearer token

Auth is off by default; set the EPANET_AUTH_* variables to gate the server behind an RS256 bearer token.

Tests

npm test

Unit tests drive the in-memory MCP transport against committed .inp fixtures — they don't require a running server.

Build a packaged installer

npm run package:win    # or package:mac / package:linux

Produces a self-contained installer (vendored Node runtime, no system Node required) under dist/.

License

MIT — see LICENSE.