Skip to main content
Glama
EPANET MCP Server

EPANET MCP Server

by hjlrosales

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.

Related MCP server: Autodesk MCP Platform

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.

Available Tools

33 tools
add_tankA

Add a storage tank at a strategic location: a new tank node plus a connector pipe attaching it to an existing node — a junction (e.g. a low-pressure junction that needs pressure support) or, optionally, a reservoir. The edit is validated against the EPANET engine before it is applied — unique ids, realistic geometry, the edited model must re-parse with the tank and pipe present, node/link counts must increase by exactly one each, and the edited model must still solve hydraulically if the base model did. Previous simulation results are invalidated; re-run run_simulation to see the effect.

Inputs: pipeId (required), tankId (required), diameter (required), maxLevel (required), +10 more.

add_valveA

Insert a pressure-reducing valve (PRV) in series with an existing pipe: the pipe is split — a new junction is created at a fraction along it, the original pipe is shortened to that junction, and a new PRV link runs from the junction to the pipe's downstream node, capping pressure there at the requested setting (e.g. to protect low-lying tap stands from excess static head). The edit is validated against the EPANET engine before it is applied — unique ids, realistic bounds, the edited model must re-parse with the junction as a junction, the valve as a PRV with the requested setting, and the pipe shortened as requested, node/link counts must increase by exactly one each, and the edited model must still solve hydraulically if the base model did. Previous simulation results are invalidated; re-run run_simulation to see the effect.

Inputs: linkId (required), setting (required), valveId (required), networkId (required), +4 more.

assign_demandsA

Convert a population table into per-node base demands for a loaded network: demand = people × litersPerCapitaPerDay × peakingFactor ÷ 86400, converted from liters/second into the model's flow units (so GPM/CFS/MGD models get the right numbers automatically). The computed demands replace each junction's base demand through the same guarded, engine-validated path as set_junction_demand: every junction must exist, junctions with demand categories in the [DEMANDS] section are rejected (they override the [JUNCTIONS] column), each computed demand must be within the model's demand bounds, and the edited model must re-parse with exactly the requested demands and unchanged node/link counts. Previous simulation results are invalidated — re-run run_simulation afterwards. This is the 'population in, demands out' step of the GIS workflow (mcp_gis_roadmap.md Phase 3).

Inputs: networkId (required), perCapita (required), population (required).

calculate_minor_lossA

Calculate total minor (dynamic) head loss through a set of pipe fittings using the K-factor method: h = K × v² / (2g). Provide a pipe diameter, flow rate, and a list of fitting types with quantities. Each fitting's K-factor is looked up from the built-in database (use list_fitting_kfactors to see available types), or supply a customK for non-standard fittings. Returns: flow velocity, individual fitting losses, total minor loss, total equivalent length of pipe, and pressure drop. Use this to account for valves, elbows, tees, and other fittings when sizing pipes or pumps.

Inputs: fittings (required), flowRate (required), flowUnits (required), diameterMm (required).

create_networkA

Build a new hydraulic model from scratch — no file needed. Supply junctions, reservoirs (e.g. a river intake) and optional tanks with elevations, plus pipes with lengths and diameters; optional x/y coordinates per node are written into a [COORDINATES] section so the model has real geometry. The spec is validated (unique ids, real pipe endpoints, realistic bounds) and the generated INP is re-opened through the EPANET engine: it must parse with exactly the requested node/link counts. Solvability is reported (solves: true/false) but not enforced, so a skeleton network can be created and filled in later. Creates a normal session: run_simulation, set_* edits, optimize_network and save_network all work on it immediately. This is the first step of the GIS workflow; for an auto-layout from real streets use generate_network_from_bbox (Phase 4) instead — see mcp_gis_roadmap.md.

Inputs: pipes (required), junctions (required), reservoirs (required), tanks, +4 more.

fetch_road_networkA

Fetch the road network for a geographic bounding box from OpenStreetMap (fixed public Overpass endpoint only — never Nominatim, never a caller-supplied URL) and return structured road geometry and attributes for future EPANET network generation: OSM way id, name, highway classification, full WGS84 geometry, length (m), and lanes/maxspeed/surface/oneway/bridge/tunnel where OSM has them (missing tags come back null). When waterwayTypes is set, matching linear waterway ways (river/stream/brook/canal/drain/ditch — for river-intake placement) are fetched in the same request and returned under waterways with way id, name, waterway class, geometry, length (m), and width/intermittent/tunnel. The bounding box is validated (ranges, min < max, per-axis span and total area caps) and the results are capped (maxResults, default 500, hard cap 5000) and pageable (offset; roads and waterways are paged independently with the same offset/maxResults). The Overpass query requests only the requested highway/waterway classes (roadTypes/waterwayTypes whitelists; roadTypes defaults to the standard drivable set, waterwayTypes is off unless given), carries a descriptive User-Agent, has a 30 s timeout and a 25 MB response cap, and fails closed on any Overpass error/timeout. Identical (bbox, roadTypes, waterwayTypes) requests are served from a short-lived in-memory cache. PURE READ: no network session, model, or file is touched — nothing is generated or optimized yet. Data © OpenStreetMap contributors, licensed ODbL (https://www.openstreetmap.org/copyright).

Inputs: maxLat (required), maxLon (required), minLat (required), minLon (required), +4 more.

friction_lossA

Calculate friction loss (head loss and pressure drop) in a full-bore water pipe. Supports two methods: Hazen-Williams (empirical, uses C-factor, water-only) and Darcy-Weisbach (physics-based, uses absolute roughness ε, universally applicable). Returns head loss per metre, total head loss over the pipe length, pressure drop, flow velocity, Reynolds number, and the Darcy friction factor. Roughness presets are available for common pipe materials (hdpe, pvc, di-cement, steel-new, steel-aged, etc.) or supply custom values. Use this to validate pipe sizing from recommend_diameter or to compare friction losses across materials/ diameters.

Inputs: method (required), lengthM (required), flowRate (required), flowUnits (required), +4 more.

generate_network_from_bboxA

Build a water network automatically from real streets — the one-call GIS layout (roadmap Phase 4, native tool). Fetch OSM highway+waterway ways for a bbox (or reuse a saved extract via osmExtract/osmFile), derive the junction/pipe skeleton: the connected component containing the road nearest the river, dead-end spurs pruned (minDeadEndM, default 30 m), roads decimated to ~spacingM (default 150 m) junction spacing, and pipe diameters from the road class as HDPE (PE100) INTERNAL bores at SDR 11 — e.g. trunk 290, primary 258, secondary 205, tertiary 164, residential 90, service 74 mm — with the default pipe material HDPE (Hazen-Williams C = 130). The reservoir is placed at the nearest OSM waterway point to river and connected to the nearest junction by an intake pipe; ground elevations are sampled from the bundled IFSAR 10 m DEM (never guessed, same fail-closed contract as create_network elevationSource). The resulting model is engine-validated and becomes a normal session (networkId): run_simulation, assign_demands, optimize_network and save_network all work on it immediately. The bbox mode calls the public Overpass API (fixed endpoint, 30 s timeout, 25 MB response cap); pass osmExtract or osmFile instead to work from a saved extract with no network. Provide exactly one of bbox / osmExtract / osmFile, plus river and a positive reservoirHead (the intake/pump discharge head — a design input, never guessed).

Inputs: river (required), reservoirHead (required), bbox, title, +4 more.

get_coordinatesA

Read the model's node coordinates (the [COORDINATES] section) without saving a file — pure read, nothing is modified. Returns each requested node's stored x/y (the model's own coordinate system) plus, when coordinates is given, its WGS84 lat/lon (coordinates: 'wgs84' means x is longitude/y is latitude; {utmZone} means x/y are UTM easting/northing meters in that zone). Nodes without stored coordinates come back in missingIds — never invented. Pass specific node ids to keep the response small, or page with offset + the 250-item cap. This is the geometry half of the GIS workflow: get_coordinates to inspect where nodes are, then sample_elevations for real IFSAR ground elevations at those points.

Inputs: networkId (required), offset, nodeIds, coordinates.

get_network_summaryB

Return a summary of a loaded network: counts, simulation timing, units, quality type, and node/link id previews.

Inputs: networkId (required).

get_node_resultsA

Query simulation results for nodes. Defaults to the last timestep and includes min/max/mean over time unless timesteps are given. Node ids are capped at 250, timesteps at 100. Pass the runId returned by run_simulation to pin results to a specific run; omit for the latest run. Units and a qualityAnalyzed flag are included in every response. Demand for tanks/reservoirs is net inflow; tank pressure is 0 by definition.

Inputs: networkId (required), runId, offset, nodeIds, +2 more.

get_nodesA

Inspect static properties of network nodes (junctions: elevation/demand; reservoirs: head; tanks: levels/diameter). Pass specific node ids to keep the response small; omit to get a capped listing.

Inputs: networkId (required), offset, nodeIds.

list_fitting_kfactorsA

List K-factors (minor loss coefficients) for common pipe fittings. Returns a table of fitting names, K-factors, categories, and equivalent-length ratios. Filter by category: valve, elbow, tee, other, or all. Use this to find the correct K-factor before calling calculate_minor_loss, or to compare loss characteristics of different fitting types.

Inputs: category.

list_networksA

List the networks currently loaded in this server session (id, source file, whether results exist). Use to recover a network id after losing it.

Inputs: no named parameters.

load_networkA

Load an EPANET INP model from the server's data directory into a named session. Returns the network id and counts.

Inputs: inputFile (required).

lookup_pipe_diametersA

Look up standard pipe inner diameters for common water-distribution materials. Returns a table of standard sizes with nominal diameter, outer diameter, wall thickness, and the resulting inner diameter — the value EPANET uses for hydraulic modeling. Materials: HDPE (ISO 4427, PE100 SDR 11), PVC (AWWA C900 DR 18), ductile iron (ISO 2531 class K9), carbon steel in three variants: steel-medium (ISO 4200 medium series), steel-sch40 (ANSI B36.10 Schedule 40/STD), steel-sch80 (ANSI B36.10 Schedule 80/XS). Filter by material, minimum/maximum nominal size, and display units (mm, inches, or both). Use this when sizing pipes, choosing a standard diameter for set_pipe_diameter, or comparing materials for a given nominal size.

Inputs: material (required), units, maxNominal, minNominal.

optimize_networkA

Search for the best combination of edits by evaluating an explicit grid of candidate choices on COPIES of a loaded network. For each variable (pipe diameter, junction demand, pump speed, or add_tank placement) you list the choices to try — for add_tank, the nodes to attach a tank to (junctions or reservoirs; plus, by default, the baseline with no tank, so 'try a tank at J2 vs R1 vs none' is one variable); every combination is validated against the EPANET engine and simulated, and the combination that minimizes/maximizes the chosen metric is returned with its full aggregate results. The base model and its stored results are NEVER modified. The search space (product of all choice lists) must fit within maxEvaluations (default 20, up to 100).

Inputs: networkId (required), objective (required), variables (required), quality, +1 more.

pipe_sizing_wizardA

End-to-end pipe sizing wizard: given a flow rate, pipe length, and material, finds every standard pipe size that satisfies velocity AND friction-loss constraints, then ranks them by suitability. Chains velocity-based diameter recommendation with Hazen-Williams or Darcy-Weisbach friction-loss validation in a single call. Supports velocity presets (distribution/transmission/service/suction), roughness presets (hdpe/pvc/di-cement/steel-new etc.), and optional max head-loss or max pressure-drop filters. Returns the top N candidates ranked by a composite score (60% velocity closeness + 40% head-loss efficiency). Each candidate includes: nominal size, inner diameter, velocity, head loss per metre, total head loss, pressure drop, Reynolds number, flow regime, and the friction factor. Use this to make a single validated pipe selection without calling recommend_diameter and friction_loss separately.

Inputs: lengthM (required), flowRate (required), flowUnits (required), topN, +10 more.

pump_selectionA

Size a centrifugal pump for a required flow rate and total dynamic head. Computes hydraulic power, brake (shaft) power, motor nameplate power with safety factor, specific speed for pump-type classification (radial/mixed/axial flow), NPSH available from suction conditions, and suggests standard motor sizes and compatible speeds. Estimates pump efficiency automatically from the power level, or accept a user-specified value. Returns a complete pump sizing summary suitable for procurement or EPANET pump-curve entry. Use this after pipe_sizing_wizard to size the pump for a validated pipe network.

Inputs: flowRate (required), flowUnits (required), totalHeadM (required), speed, +5 more.

recommend_diameterA

Recommend standard pipe diameters for a given flow rate and target velocity range. Given a design flow (in any EPANET flow unit) and an acceptable velocity window, computes the ideal inner diameter using Q = v × πd²/4, then returns every standard pipe size (from HDPE, PVC, ductile iron, or steel in medium/Sch 40/Sch 80 variants) whose inner diameter produces a velocity within the range. Each recommendation includes the resulting velocity, an approximate Reynolds number (for turbulence check), and the standard it comes from. Use presets (distribution, transmission, service, suction) for typical velocity ranges, or specify custom min/max. Pipe diameters returned are the inner-diameter values to use with set_pipe_diameter.

Inputs: flowRate (required), flowUnits (required), preset, material, +2 more.

remove_tankA

Remove a storage tank and every pipe attached to it (the inverse of add_tank). The edit is validated against the EPANET engine before it is applied — unique id, the edited model must re-parse with the tank and its connector pipes gone, node count must decrease by exactly one and link count by exactly the removed pipes, and a previously-solvable network must still solve. If controls or rules reference the tank, the engine rejects the edit (fail-closed) rather than leaving a dangling reference.

Inputs: tankId (required), networkId (required).

run_candidateA

Evaluate a scenario: apply a batch of edits (pipe diameters, junction demands, pump speeds) to a COPY of a loaded network, validate the copy against the EPANET engine, run a simulation, and return the aggregate results (same shape as run_simulation). The base model and its stored results are NEVER modified, so candidates can be compared freely and previous runs stay valid.

Inputs: edits (required), networkId (required), quality.

run_simulationA

Run the EPANET hydraulic simulation for a loaded network and return aggregate results (min/max/average pressure and flow, pump energy, warnings). Results are stored so get_node_results / get_link_results can query them.

Inputs: networkId (required), quality.

sample_elevationsA

Sample real ground elevations from the bundled IFSAR 10 m DEM (Philippines) for WGS84 points, or for the nodes of a loaded network whose x/y coordinates are WGS84 (or UTM with a zone). Pure read — nothing is modified. Returns elevation in meters per point, bilinearly interpolated from the 2x2 pixel neighborhood; points outside the tile grid or over nodata come back with elevation null. The bundled DEM is the default elevation source for create_network (elevationSource), so this is the first call in the GIS workflow: sample, then build or set_node_elevation. Configure the data folder with EPANET_DEM_DIR (defaults to the repo's apps/app/public/dem/ifsar-10m).

Inputs: points, source, nodeIds, networkId, +1 more.

save_networkA

Write the current state of a loaded network (including any set_* edits applied so far) to a file in the server's data directory: EPANET INP text (format 'inp', default) or the app's .net container (format 'net', which embeds the INP text — load_network reads both). The model is re-validated through the EPANET engine before writing, and existing files are not overwritten unless overwrite: true. Use this to persist edits: after saving, load_network can read the file back on a fresh session or server restart.

Inputs: networkId (required), format, overwrite, outputFile.

set_demand_patternA

Add or replace a demand pattern ([PATTERNS]) and attach it to one or more junctions, so base demands vary over the simulation (e.g. an hourly diurnal curve with morning and evening peaks). The edit is validated against the EPANET engine before it is applied: the pattern id must be valid, each multiplier must be between 0 and 10 (and not all zero), every listed junction must exist and be a junction, and the edited model must re-parse with the pattern present at exactly the requested length and values, attached to each junction's demand, with node/link counts unchanged. A previously-solvable model must still solve. An existing pattern with the same id is replaced in place; a junction already using a pattern gets this one instead. Previous simulation results are invalidated — re-run run_simulation afterwards (get_node_results with timesteps returns the hourly variation).

Inputs: networkId (required), patternId (required), junctionIds (required), multipliers (required).

set_junction_demandA

Change the base demand of a junction in a loaded network. The edit is validated against the EPANET engine before it is applied: the node must exist and be a junction, the value must be within realistic bounds, and the edited model must re-parse with the requested demand. Junctions whose demand is overridden by the [DEMANDS] section are rejected. Previous simulation results for the network are invalidated (they describe the old model) — re-run run_simulation afterwards.

Inputs: demand (required), nodeId (required), networkId (required).

set_node_elevationA

Change the elevation of a junction, reservoir (its fixed head), or tank (its bottom elevation) in a loaded network. The edit is validated against the EPANET engine before it is applied: the node must exist and be a junction/reservoir/tank, the value must be within realistic bounds for the model's units, and the edited model must re-parse with the requested elevation. Previous simulation results for the network are invalidated (they describe the old model) — re-run run_simulation afterwards.

Inputs: nodeId (required), elevation (required), networkId (required).

set_pipe_diameterA

Change the diameter of a pipe in a loaded network. The edit is validated against the EPANET engine before it is applied: the pipe must exist and be a pipe, the value must be within realistic bounds for the model's units, and the edited model must re-parse with the requested diameter. Previous simulation results for the network are invalidated (they describe the old model) — re-run run_simulation afterwards.

Inputs: linkId (required), diameter (required), networkId (required).

set_pump_speedA

Change the relative speed setting of a pump in a loaded network. The edit is validated against the EPANET engine before it is applied: the link must exist and be a pump, the value must be within realistic bounds, and the edited model must re-parse with the requested speed. If the pump has no SPEED property yet, one is appended to its [PUMPS] line. Previous simulation results for the network are invalidated (they describe the old model) — re-run run_simulation afterwards.

Inputs: speed (required), linkId (required), networkId (required).

set_valve_settingA

Change the setting of a valve (PRV/PSV/PBV pressure, FCV flow, TCV loss coefficient) in a loaded network. The edit is validated against the EPANET engine before it is applied: the link must exist and be a valve, the value must be within realistic bounds for the valve type and the model's units, and the edited model must re-parse with the requested setting. GPV valves are rejected (their setting is a headloss curve id). Previous simulation results for the network are invalidated (they describe the old model) — re-run run_simulation afterwards.

Inputs: linkId (required), setting (required), networkId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 33 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, even within the design/sizing cluster (e.g., recommend_diameter vs. pipe_sizing_wizard, friction_loss vs. calculate_minor_loss). The set_* tools target different properties, and generate_network_from_bbox vs. fetch_road_network are separate phases. No two tools appear to do the same thing.

    Naming Consistency4/5

    The majority of tools follow the verb_noun snake_case pattern (load_network, run_simulation, set_pipe_diameter). A few tools break this pattern with noun-first names (friction_loss, pipe_sizing_wizard, pump_selection), but the overall style is consistent and readable.

    Tool Count4/5

    33 tools is on the high side, but the server covers a comprehensive range: network lifecycle, simulation, editing, optimization, GIS integration, and hydraulic design. Each tool is justified by the domain's breadth, so the count feels appropriate rather than excessive.

    Completeness5/5

    The tool surface is remarkably complete: create/load/save/list networks, run simulations, inspect and edit all key elements, add/remove tanks/valves, optimize, and a full set of design tools (diameter, friction, pump sizing, minor losses, GIS sampling). No obvious dead ends; only a delete_network is missing, which is a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets any MCP-compatible AI assistant read and edit Autodesk Civil 3D drawings through tools for alignments, surfaces, corridors, pipe networks, quantity takeoff, and cut/fill, using a local bridge plugin and named pipes.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to inspect Ignition gateway backups, project exports and tag exports locally and turn them into an editable engineering reference and manual pack workspace. Runs over stdio so agents can explain, validate and complete the evidence-traced documents without uploading anything.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to inspect and modify maps and scenes open in a locally running desktop GIS session through natural language, exposing 38 fixed tools for session and layer queries, fields, selection, visibility and renaming, symbology, transparency, camera and elevation, map switching, raster, layout export, whitelisted geoprocessing, and attribute editing. It routes stdio MCP calls through a Windows named pipe to a C# add-in, with no network ports and no arbitrary code execution.
      MIT