hecras-mcp

An MCP server that lets Claude run HEC-RAS headless: inspect projects, execute plans and read results.

HEC-RAS is the US Army Corps of Engineers' river hydraulics software. It is a Windows desktop application with no usable programmatic API. This server wraps it in the Model Context Protocol so an AI agent (Claude Code, Claude Desktop) can drive 1D steady, 1D unsteady and 2D models end to end.

Status: 19 tools · 126 automated tests passing (113 library tests + 13 end-to-end MCP protocol tests), including a full 2D simulation and validation against USACE's official Muncie 2D model mesh.

📄 Full technical notes in Spanish: README.es.md

Why this was harder than it looks

Every item below failed silently or with a misleading error, and each one cost real debugging time.

Related MCP server: ras-commander-mcp

Architecture

Tools

Arguments plan, geometry and flow are file extensions (p01, g01, f01), not full paths.

Testing: physical validation, not just "it didn't crash"

Tests run on disposable synthetic models generated in sandbox/ and never touch a real model.

• Steady 1D: discharge conserved exactly (50 / 150 / 300 m³/s); uniform flow drops 1.00 m per 1000 m (= bed slope); energy line always above the water surface; normal depth of 1.726 m checked by hand against Manning's equation.

• Unsteady 1D: the inflow hydrograph is reproduced (peak 320 m³/s), the flood wave rises and recedes, and the peak attenuates downstream (320 → 310.5 m³/s).

• 2D: 1,104 seeded points → 1,246 cells / 2,279 faces, run finishes with 0.016 % volume balance error; the max water level follows the hydrograph and never drops below the minimum terrain elevation.

• Deliberate failures: paths outside the allow-list, missing projects, GIS .prj files, nonexistent plans/sections, malformed discharge lists, invented variables, results requested before computing, corrupted geometry, timeouts, 2D tools on a 1D model, and the regional-date failure. Each one must fail cleanly, with an explanation.

.venv\Scripts\python.exe tests\run_tests.py      # 113 library tests
.venv\Scripts\python.exe tests\test_protocol.py  # 13 MCP protocol tests

The official USACE Muncie model (used to validate reading a production mesh: 5,765 cells, 11,164 faces) is not included because of its size. Get it from USACE's Example_Projects_7_0.zip with tests/extract_example.ps1; if it's missing, that stage is skipped automatically.

Setup

Requirements: Windows, HEC-RAS 7.0.x, Python 3.10+.

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
claude mcp add hecras --scope user "C:\path\to\hecras-mcp\start_hecras_mcp.cmd"

Configure in start_hecras_mcp.cmd:

• HECRAS_MCP_ROOTS — folders the server may read and write (;-separated). Everything else is rejected.

• HECRAS_EXE (optional) — a specific Ras.exe. Without it, the installation is detected from the Windows registry.

• HECRAS_VERSION (optional) — choose among several installations, e.g. 6.5.

Not covered

Geometry authoring through the tools, unsteady hydrograph editing, bridges and structures, sediment transport, water quality and inundation mapping (RAS Mapper).

Built by Oscar Daniel Montero Miranda. Independent project, not affiliated with or endorsed by USACE or the Hydrologic Engineering Center. Code comments are in Spanish.