ras-commander-mcp by gpt-cmdr - MCP Server

HEC-RAS MCP Server

The RAS Commander MCP (Model Context Protocol) server provides tools for querying HEC-RAS project information using the ras-commander library. This allows Claude Desktop to interact with HEC-RAS hydraulic modeling projects.

RAS Commander MCP is an open-source, LLM-forward H&H automation tool provided under MIT license by CLB Engineering Corporation. This is third-party software and is not made by or endorsed by the U.S. Army Corps of Engineers (USACE) Hydrologic Engineering Center (HEC).

For a demonstration of CLB's H&H automation services, contact us at

Features

Query comprehensive HEC-RAS project information (plans, geometries, flows, boundaries)
Extract detailed plan results including unsteady simulation info and runtime metrics
Explore HDF file structures and extract computation messages
Support for multiple HEC-RAS versions (6.5, 6.6, etc.)
Formatted text output suitable for LLM interaction
Error handling with helpful diagnostics

Future Features

List Geometry Elements 1D List Rivers/Reaches 1D Cross Sections by River and Reach 2D Reference Lines Boundary Lines 1D and 2D Structures
Summary Results at Boundaries (Max WSE and Max Flow)
Also Structures (list them all with max wse snd max flow)
Detailed XSEC results table (by river/reach) for debugging
HEC-RAS Documentation Search Capability (return relevant confluence document links via RAG or deep research)

Prerequisites

HEC-RAS Installation: HEC-RAS must be installed on your system (default expects version 6.6)
Python: Python 3.10+
Claude Desktop: For MCP integration
uv: Python package manager (recommended)

Installation

Using uv (Recommended)

Install uv if you haven't already:

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Clone this repository:

git clone <repository-url>
cd ras-commander-mcp

The dependencies will be automatically installed when you run the server with uvx (see Configuration below).

Using pip (Alternative)

If you prefer to use pip:

pip install mcp ras-commander pandas

Configuration

Claude Desktop Integration (Recommended)

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

Option 1: From Git Repository (Automatic Updates)

{
  "mcpServers": {
    "hecras": {
      "command": "uvx",
      "args": [
        "--from", "ras-commander-mcp@git+https://github.com/gpt-cmdr/ras-commander-mcp.git",
        "ras-commander-mcp"
      ],
      "env": {
        "HECRAS_VERSION": "6.6"
      }
    }
  }
}

Option 2: Local Development Installation

If you've cloned the repository locally for development:

{
  "mcpServers": {
    "hecras": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\path\\to\\ras-commander-mcp-main", "ras-commander-mcp"],
      "env": {
        "HECRAS_VERSION": "6.6"
      }
    }
  }
}

Option 3: Direct Python Execution

Alternative approach using Python directly:

{
  "mcpServers": {
    "hecras": {
      "command": "uv",
      "args": ["run", "python", "C:\\path\\to\\ras-commander-mcp-main\\server.py"],
      "env": {
        "HECRAS_VERSION": "6.6"
      }
    }
  }
}

HEC-RAS Version Configuration

The MCP server uses HEC-RAS version 6.6 by default. To use a different version:

Set HEC-RAS Version (if you have a different version installed):

{
  "mcpServers": {
    "hecras": {
      "command": "uvx",
      "args": [
        "--from", "ras-commander-mcp@git+https://github.com/gpt-cmdr/ras-commander-mcp.git",
        "ras-commander-mcp"
      ],
      "env": {
        "HECRAS_VERSION": "6.5"
      }
    }
  }
}

Set HEC-RAS Path (if HEC-RAS is installed in a non-standard location):

{
  "mcpServers": {
    "hecras": {
      "command": "uvx",
      "args": [
        "--from", "ras-commander-mcp@git+https://github.com/gpt-cmdr/ras-commander-mcp.git",
        "ras-commander-mcp"
      ],
      "env": {
        "HECRAS_PATH": "C:\\Program Files\\HEC\\HEC-RAS\\6.5\\HEC-RAS.exe"
      }
    }
  }
}

Testing Configuration

Before adding to Claude Desktop, test your configuration:

# For local development:
cd path/to/ras-commander-mcp-main
set HECRAS_VERSION=6.6
uv run ras-commander-mcp

# Should start successfully showing:
# Starting HEC-RAS MCP Server...
# RAS Commander MCP by CLB Engineering Corporation

Usage

Available Tools

All tools provided by this MCP server leverage the ras-commander Python library for advanced HEC-RAS automation capabilities.

hecras_project_summary: Get comprehensive or selective project information
- Parameters:
  - project_path (required): Full path to HEC-RAS project folder
  - show_rasprj (optional): Show project file contents (default: true)
  - show_plan_df (optional): Show plan files and metadata (default: true)
  - show_geom_df (optional): Show geometry files (default: true)
  - show_flow_df (optional): Show steady flow data (default: true)
  - show_unsteady_df (optional): Show unsteady flow data (default: true)
  - show_boundaries (optional): Show boundary conditions (default: true)
  - show_rasmap (optional): Show RASMapper configuration (default: false)
  - showmore (optional): Show all columns/verbose mode (default: false)
read_plan_description: Read multi-line description from a plan file
- Parameters:
  - project_path (required): Full path to HEC-RAS project folder
  - plan_number (required): Plan number (e.g., '1', '01', '02')
get_plan_results_summary: Get comprehensive results from a specific plan
- Parameters:
  - project_path (required): Full path to HEC-RAS project folder
  - plan_number (required): Plan number or full path to plan HDF file
get_compute_messages: Get computation messages and performance metrics
- Parameters:
  - project_path (required): Full path to HEC-RAS project folder
  - plan_number (required): Plan number or full path to plan HDF file
get_hdf_structure: Explore HDF file structure
- Parameters:
  - hdf_path (required): Full path to the HDF file
  - group_path (optional): Internal HDF path to start exploration from (default: "/")
  - paths_only (optional): Show only paths without details (default: false)
get_projection_info: Get spatial projection information (WKT)
- Parameters:
  - hdf_path (required): Full path to the HDF file

Example Usage in Claude

Once configured, you can ask Claude:

"Query the HEC-RAS project at C:/Projects/MyRiverModel"
"Show me the plans in the Muncie test project"
"Get the results summary for plan '01' in my project"
"Show me the compute messages for plan '1'"
"Explore the HDF structure of my results file"
"Get the projection info from my terrain HDF"

Python Library Reference

This MCP server is built on top of the ras-commander Python library, which provides comprehensive programmatic access to HEC-RAS projects. For advanced Python scripting and automation beyond what's available through the MCP interface, refer to the ras-commander documentation.

Testing

Running Tests

From the project directory, run the complete test suite:

# Install dependencies and run all tests
uv sync
uv run python tests/test_server.py          # Basic server functionality
uv run python tests/test_all_tools.py       # Comprehensive tool validation  
uv run python tests/test_single_tool.py     # Single tool testing utility

Test outputs are saved to tests/outputs/ as markdown files for review.

Test Data

The testdata/ folder contains complete HEC-RAS projects for testing:

Muncie/: Complete project with terrain, results, and boundary conditions
BeaverLake/: Additional test project

Troubleshooting

ImportError for ras-commander: Ensure HEC-RAS is properly installed
Project not found: Verify the project path exists and contains .prj files
Version errors: Check that the specified HEC-RAS version matches your installation
MCP connection issues: Verify Claude Desktop configuration and restart Claude

Development

To modify or extend the server:

Clone the repository
Make changes to server.py
Test with: uv run python tests/test_all_tools.py
Update Claude Desktop configuration if needed

License

This project is licensed under the MIT License - see the file for details.

Trademarks

See for trademark information and compliance policies.

About

RAS Commander MCP is developed and maintained by CLB Engineering Corporation as part of our commitment to advancing H&H automation through open-source tools.

For professional H&H automation services and custom solutions, contact us at