README.md

---
title: EPANET MCP Server
emoji: 💧
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: EPANET/ePyT water-network modelling over MCP (HTTP + SSE)
---

# 💧 EPANET MCP Server

A remote [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
EPANET water-distribution modelling — powered by [ePyT](https://github.com/KIOS-Research/EPyT) —
to any MCP-capable client. Load `.inp` models, run hydraulic/quality simulations, modify
parameters, and generate what-if scenarios in natural language.

It wraps the upstream [`epanet-mcp-server`](https://pypi.org/project/epanet-mcp-server/)
(44 tools) and serves it over **both** modern transports at once, behind an optional API key.

## Endpoints

| Transport | Path | Clients |
|-----------|------|---------|
| Streamable HTTP | `/mcp` | HuggingChat, Codex, Perplexity, Gemini, ChatGPT (dev mode) |
| HTTP + SSE | `/sse` | Claude Desktop (via `mcp-remote`), other legacy clients |
| Health probe | `/health` | uptime checks (no auth) |

Base URL once deployed: `https://<owner>-<space-name>.hf.space`

## Authentication

Set a Space **secret** named `CLIENT_API_KEY`. When present, every request to `/mcp`,
`/sse`, and `/messages/` must send it:

```
Authorization: Bearer <YOUR_KEY>
```

(`X-API-Key: <YOUR_KEY>` is also accepted.) Leave the secret unset to run open — useful for
ChatGPT connectors, which only support OAuth or no-auth. `/` and `/health` are always public.

## Networks

ePyT ships 52 benchmark networks (Net1/2/3, Hanoi, Anytown, L-TOWN, Balerma, …) — call
`list_bundled_networks` to see them. Custom networks are bundled under
`/home/user/app/networks/` and loaded by absolute path, e.g.:

```
load_network("/home/user/app/networks/net3.inp", "net3")
```

Bundled here: `net3.inp`, `net3_PDD.inp`, `ky4.inp`, `ky10.inp`, `Net6.inp`, `BIWS.inp`.

## Smoke test

`smoke_test.py` runs the full MCP handshake (initialize → tools/list → tools/call) over
both transports and checks the auth gate:

```
python smoke_test.py --base-url https://<owner>-<space-name>.hf.space --api-key <YOUR_KEY>
```

See `CLIENTS.md` for copy-paste connection configs for each client.

Built on `epanet-mcp-server` by Applied-AI-Eurecat (MIT).