RAS Commander MCP

RAS Commander MCP provides bounded, read-only information from HEC-RAS project and plan text through the public RAS Commander Python API. It requires no HEC-RAS executable. The fuller modeling, analysis and GIS experience uses RAS Commander and its Python workflows outside MCP.

This independent open-source project complements HEC's work. It is not affiliated with or endorsed by USACE HEC. Official HEC references remain passive reader links.

Scope

The explicit tool set covers server/version information, project length units, plan descriptions, and selected project/plan metadata. Project metadata and plan configuration use the RasText API published in ras-commander 0.104.0. On ras-commander 0.103.0, units and descriptions work and metadata tools return an actionable availability error. See compatibility.

Project tools belong only in bounded informational subagents. Each delegation specifies the question, configured root, named file, selected fields, row and character limits, and answer format. The child returns a compact answer with source identity, installed versions, missing data and truncation. A host without subagent tool isolation should use a scoped Python workflow instead of exposing project tools to its main coordinator.

Claude Code users should install the ras-commander@ras-commander-plugin plugin from the gpt-cmdr/ras-commander-plugin marketplace (forthcoming; the repository is not yet published). The plugin covers the RAS and HMS text servers. It declares the server at plugin level, supplies a plugin subagent for bounded reads, and adds a PreToolUse guard that denies project tools to the main session. A subagent-only isolation check passed in Claude Code 2.1.287 on October 5, 2026. The plugin does not copy agent files into the user's ~/.claude/agents directory. Other hosts require their own isolation configuration.

MCP does not modify projects, compute, read HDF/DSS, inspect geometry/coordinates, extract gridded data, export files, download into projects, or execute arbitrary code. Large and repeated drilldowns use Python. Tool annotations describe this boundary; descriptor checks, allowlists and bounded snapshots enforce the reads.

Install and configure

Use Python 3.10+ and an authorized managed environment:

python -m pip install --upgrade ras-commander-mcp

Preserve an existing pin or lock when required. Version 0.4 replaces the 0.3 tool set; it needs ras-commander 0.104.0 or later for project metadata and plan configuration, and reports those tools as unavailable on older releases.

A client that launches servers through uv can run uvx ras-commander-mcp instead of a separate install; uv builds and caches the environment on first launch. claude_desktop_config.json shows the equivalent uvx --from ras-commander-mcp ras-commander-mcp form.

Set RAS_MCP_ALLOWED_ROOTS to a JSON array of absolute, resolved project roots. No roots are trusted by default. On Linux/macOS:

export RAS_MCP_ALLOWED_ROOTS='["/home/user/projects/example"]'
ras-commander-mcp

On PowerShell:

$env:RAS_MCP_ALLOWED_ROOTS = '["C:\\Projects\\Example"]'
ras-commander-mcp

The server uses stdio. Configure the executable and environment in a client that routes project tools to subagents. claude_desktop_config.json illustrates transport configuration, not proof that desktop clients provide this routing. No project query performs package installation or an automatic upgrade.

Update an installation

Close the MCP client before updating so that no running server holds the environment. server_information(check_updates=true) reports the installed and latest PyPI versions of ras-commander-mcp, ras-commander and the MCP SDK without changing the environment.

Managed pip environment. Name both packages:

python -m pip install --upgrade ras-commander-mcp ras-commander

pip's default upgrade strategy keeps an installed dependency that still satisfies the requirement. With pip 23.0.1, upgrading only ras-commander-mcp left ras-commander 0.103.0 in place.

Cached uvx ras-commander-mcp. Keep the client configured with the plain command. Each launch resolves current compatible releases, but uv reuses its cached PyPI index data while that data is fresh (PyPI currently allows 10 minutes). To use a new release immediately, run once:

uvx --refresh --from ras-commander-mcp python -c "from importlib.metadata import version as v; print(v('ras-commander-mcp'), v('ras-commander'))"

The command refreshes the index data, builds the current environment and prints both versions. The next plain uvx ras-commander-mcp launch reuses that environment. The server accepts no command-line options, so the refresh runs Python instead of starting the server. uv cache clean ras-commander-mcp ras-commander has the same effect on the next launch; name both packages, because cleaning only ras-commander-mcp left ras-commander 0.103.0 in place.

uv tool install ras-commander-mcp. uvx prefers an installed tool to its cache, and --refresh does not change that tool. Run uv tool upgrade ras-commander-mcp.

These results were observed on October 5, 2026, with uv 0.12.23 on Linux. A local index served the 0.3.2/0.4.0 and 0.103.0/0.104.0 wheels with PyPI's cache header, and the refresh command was repeated against PyPI. Preserve deliberate pins and locks; no tool call installs or upgrades packages.

Windows long paths

Version 0.4.0 opens validated project files through Windows extended-length paths (\\?\ and \\?\UNC\), so files beyond the 260-character MAX_PATH limit are readable. Root, traversal and opened-handle checks are unchanged. Other tools in a workflow, including Python scripts, may still fail on long paths. An administrator can enable Windows long-path support from an elevated prompt:

reg add HKLM\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1 /f

Or in an elevated PowerShell session:

New-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name LongPathsEnabled -Value 1 -PropertyType DWORD -Force

No reboot is needed; processes started after the change use the setting, and running processes, including an open MCP client, must be restarted. Each application must also declare long-path awareness.

Dependencies and version checks

Direct dependencies are the official MCP Python SDK (without CLI extras), ras-commander and packaging. The SDK has protocol/validation/network dependencies; ras-commander currently inherits numpy, pandas and h5py. This is a small adapter, not a stdlib-only installation. No GIS, Java/DSS or remote-engine extras are added.

server_information(check_updates=true) optionally checks fixed PyPI metadata endpoints with bounded responses and caching. It reports installed/latest versions and update availability; offline use remains available. Preserve deliberate user pins and refresh managed environments outside tool calls.

Qualification

Version 0.4.0 with ras-commander 0.104.0 read a corpus of 983 HEC-RAS text files with 0 errors on Linux and on Windows from a UNC project root. The 69 corpus files whose Windows path reached 260 characters failed before the extended-length change (PR #10) and passed after it. The PyPI packages reproduced the results obtained from source. These are read-contract results, not engine, hydraulic or all-client acceptance. See compatibility.

Documentation

• Tools
• Architecture and access limits
• Migration from the previous tool set
• Compatibility and release maintenance
• Installation

The full library documentation is at RAS Commander.