ras-commander-mcp 0.3.0

MCP server for querying HEC-RAS project information

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.

Key Features

• Stateful Context: Initialize a project once, then query it multiple times without repeating the project path
• Comprehensive Project Summary: Get all project info including plans, geometries, flows, and projection data
• Flexible Plan Queries: Get all plans or specific plan details
• Infiltration Analysis: Extract and analyze soil infiltration data
• Results Summary: Access unsteady flow results, volume accounting, and runtime statistics
• Smart Path Handling: Automatic HDF file detection for projection info
• Error Handling: Helpful diagnostics for common issues

Prerequisites

1. HEC-RAS Installation: HEC-RAS must be installed on your system (default expects version 6.6)
2. Python: Python 3.8+ with Anaconda recommended
3. Claude Desktop: For MCP integration

Installation

For Claude Desktop Users (Recommended)

1. Install uv (one-time setup):

   • Windows:

     powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
     

   • macOS/Linux:

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

2. Configure Claude Desktop: Add the following to your Claude Desktop configuration file:

   Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

   {
     "mcpServers": {
       "hecras": {
         "command": "uvx",
         "args": ["ras-commander-mcp"],
         "env": {
           "HECRAS_VERSION": "6.6"
         }
       }
     }
   }
   

3. Restart Claude Desktop

That's it! The MCP server will be automatically downloaded and run when needed.

For Developers

To install for development:

# Clone the repository
git clone <repository-url>
cd ras-commander-mcp

# Install in development mode with uv
uv pip install -e .

# Or with standard pip
pip install -e .

Legacy Installation (Alternative)

If you prefer the traditional approach:

1. Clone this repository:

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

2. Install dependencies using the Anaconda environment:

# Create and activate conda environment
conda create -n hecras-mcp python=3.9
conda activate hecras-mcp
pip install -r requirements.txt

Configuration

Configuration Options

You can configure the server through environment variables in the Claude Desktop config:

{
  "mcpServers": {
    "hecras": {
      "command": "uvx",
      "args": ["ras-commander-mcp"],
      "env": {
        "HECRAS_VERSION": "6.5",  // HEC-RAS version (default: 6.6)
        "HECRAS_PATH": "C:\\Custom\\Path\\To\\HEC-RAS.exe"  // Custom HEC-RAS path
      }
    }
  }
}

Legacy Configuration (for manual installation)

If you're using the legacy installation method:

{
  "mcpServers": {
    "hecras": {
      "command": "python",
      "args": ["path/to/your/ras-commander-mcp/server.py"],
      "env": {
        "HECRAS_VERSION": "6.5"
      }
    }
  }
}

Troubleshooting

If you encounter issues:

1. Verify uv installation: Run uv --version in a terminal
2. Check HEC-RAS installation: Ensure HEC-RAS is installed in the default location or set HECRAS_PATH
3. Test the server: Run uvx ras-commander-mcp in a terminal to see any error messages
4. Clear uv cache: If you have issues with updates, run uv cache clean

Available Tools

1. get_ras_projectsummary

Get comprehensive project information including plans, geometries, flows, boundaries, and projection info. This tool initializes the project context for subsequent calls.

Parameters:

• project_path (optional): Full path to HEC-RAS project folder
• include_boundaries (optional): Include boundary conditions data (default: false)

2. get_ras_planinfo

Get plan information from the project. Can return all plans or a specific plan.

Parameters:

• project_path (optional): Full path to HEC-RAS project folder
• plan_number (optional): Specific plan number (e.g., "01", "02")

3. get_ras_infiltration

Get infiltration layer data and soil statistics from the project.

Parameters:

• project_path (optional): Full path to HEC-RAS project folder
• significant_threshold (optional): Minimum percentage threshold for significant mukeys (default: 1.0)

4. get_ras_resultssummary

Get comprehensive results from a specific plan including unsteady info, volume accounting, and runtime data.

Parameters:

• plan_name (required): Name or number of the plan
• project_path (optional): Full path to HEC-RAS project folder

5. get_projection_info

Get spatial projection information (WKT string) from HDF files.

Parameters:

• hdf_path (optional): Full path to HDF file (auto-detects if not provided)

6. get_1d_profile_results

Get maximum water surface elevation and velocity for 1D cross sections in a river/reach.

Parameters:

• plan_name (required): Name or number of the plan
• river_name (optional): River name (if not specified, returns all rivers)
• reach_name (optional): Reach name (only used if river_name is specified)
• project_path (optional): Full path to HEC-RAS project folder

Returns: Formatted table with station, max WSEL, and max velocity for each cross section.

7. compare_1d_profiles

Compare maximum water surface elevations between two plans for 1D cross sections.

Parameters:

• plan1_name (required): Name or number of the first plan (baseline)
• plan2_name (required): Name or number of the second plan (comparison)
• river_name (optional): River name (if not specified, returns all rivers)
• reach_name (optional): Reach name (only used if river_name is specified)
• project_path (optional): Full path to HEC-RAS project folder

Returns: Comparison table with differences and comprehensive statistics including stations unique to each plan.

8. plot_1d_profile

Plot 1D profile results showing water surface elevation vs station.

Parameters:

• plan_name (required): Name or number of the plan to plot
• river_name (optional): River name (if not specified, shows all rivers)
• reach_name (optional): Reach name (only used if river_name is specified)
• project_path (optional): Full path to HEC-RAS project folder

Returns: Embedded PNG plot as base64 image in markdown format.

9. plot_1d_profile_comparison

Plot comparison of 1D profiles between two plans.

Parameters:

• plan1_name (required): Name or number of the first plan (baseline)
• plan2_name (required): Name or number of the second plan (comparison)
• river_name (optional): River name (if not specified, shows all rivers)
• reach_name (optional): Reach name (only used if river_name is specified)
• project_path (optional): Full path to HEC-RAS project folder

Returns: Embedded PNG comparison plot with thalweg data, annotations, and detailed statistics.

10. get_1d_xsec_timeseries

Get detailed time series results for a specific 1D cross section including water surface elevation, velocity, flow, and other hydraulic variables.

Parameters:

• plan_name (required): Name or number of the plan
• river_name (required): River name
• reach_name (required): Reach name
• station (required): River station (e.g., '27857.47')
• project_path (optional): Full path to HEC-RAS project folder

Returns: Time series data with summary statistics (max, min, mean, time of max) for each variable.

Usage Examples

In Claude Desktop

Once configured, you can ask Claude:

"Get the project summary for C:/Projects/MyRiverModel"
"Show me plan 04 details"  (no path needed after initialization!)
"Get infiltration data with 5% threshold"
"Show results summary for plan 04"
"What's the projection info?"

Key Feature: Stateful Context

The server maintains project context between calls:

1. First call - Initialize with project path:

   "Get project summary for C:/Projects/MyRiverModel"
   

2. Subsequent calls - No path needed:

   "Show me plan 02"
   "Get infiltration data"
   "Show results for plan 04"
   

3. Switch projects - Just provide a new path:

   "Get project summary for C:/Projects/AnotherModel"
   

Testing

Run the example client to test the server:

# Using the activated conda environment
python example_client.py

Or test directly without MCP protocol:

python test_server.py

Test Data

The testdata/Muncie/ folder contains a complete HEC-RAS project for testing, including:

• Multiple plan configurations
• HDF5 result files
• Terrain and infiltration data
• Geometry files
• Boundary conditions

Troubleshooting

1. ImportError for ras-commander: Ensure ras-commander is installed and HEC-RAS is properly installed
2. Project not found: Verify the project path exists and contains .prj files
3. Version errors: Check that the specified HEC-RAS version matches your installation
4. No context available: Make sure to initialize a project first with get_ras_projectsummary

Development

To modify or extend the server:

1. Edit server.py to add new tools or modify existing ones
2. Test changes with test_server.py (direct testing)
3. Test MCP integration with example_client.py
4. Update Claude Desktop configuration if needed

What's New in v0.3.0

• Enhanced 1D Profile Comparison: Properly handles mismatched stations between plans
• Improved Statistics: Separate statistics for matching vs non-matching stations
• Better Plotting: Enhanced plots with thalweg data, annotations, and visual markers
• New Tool: get_1d_xsec_timeseries for detailed cross-section time series analysis
• Outer Join Logic: Shows stations that exist in only one plan during comparisons
• Thalweg Integration: Automatic thalweg plotting from geometry data where available
• Enhanced Annotations: Plot annotations show maximum differences and locations
• Better Error Handling: More robust data extraction and error reporting

What's New in v0.2.0

• Stateful Context: Project persistence between tool calls
• Improved Tool Names: More consistent get_ras_* naming convention
• Consolidated Tools: Geometry info now included in project summary
• Smart Defaults: Auto-detection of HDF files for projection info
• Enhanced Plan Queries: Support for querying by plan number
• Better Error Messages: More helpful context-aware error handling

License

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

Trademarks

See TRADEMARKS.md for trademark information and compliance policies.