EnergyPlus MCP Server

Overview

This Model Context Protocol (MCP) server provides comprehensive access to EnergyPlus building energy simulation results through a rich set of tools for discovering, analyzing, and extracting data from EnergyPlus model files. The server includes advanced features like pandas-based data analysis, keyword-based table searching, and comprehensive logging with token consumption tracking.

Related MCP server: XRPL Data MCP

Key Features

• Comprehensive Data Access: Read epJSON input files, SQL result databases, and HTML summary reports

• Advanced Search Capabilities: Search HTML tables by keywords, find related epJSON objects, and explore model components

• Pandas Integration: Execute pandas queries directly on timeseries and tabular data

• Logging & Monitoring: Built-in token consumption tracking and function call monitoring

• Flexible Model Discovery: Automatic model cataloging and metadata extraction

Installation

# Clone the repository
git clone <repository-url>
cd mcp-eplus-outputs

# Install dependencies
uv sync

# Run the server
uv run main.py

Configuration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "mcp_eplus_outputs": {
      "command": "uv",
      "args": ["--directory", "C:/path/to/mcp-eplus-outputs", "run", "main.py"]
    }
  }
}

File Structure

Each EnergyPlus model consists of three main file types:

• .epJSON - Input model definition (building geometry, materials, HVAC systems, schedules)

• .sql - Simulation results database (hourly timeseries data, summary tables)

• .table.htm - HTML summary reports (tabular summaries of results)

Model Naming Convention

Files follow this pattern: {CODENAME}_{PROTOTYPE}_{CODEYEAR}_{CITY}_{SKIPOPTIONS}_{HVAC_LABEL}.{EXTENSION}

Example: ASHRAE901_HotelLarge_STD2025_Buffalo_SkipEC_gshp.epJSON

Available Data

Building Types

• HotelLarge - Large hotel building prototype

• Warehouse - Warehouse building prototype

HVAC Systems

• gshp - Ground Source Heat Pump

• pkgdx_gas - Packaged DX with Gas

• pkgdx_hp - Packaged DX Heat Pump

• pvav_awhp - Packaged VAV with Air-to-Water Heat Pump

• pvav_blr - Packaged VAV with Boiler

• vav_ac_blr - VAV with Air-Cooled Chiller and Boiler

• vav_ac_blr_doas - VAV with Air-Cooled Chiller, Boiler, and DOAS

• vav_wc_blr - VAV with Water-Cooled Chiller and Boiler

• vrf - Variable Refrigerant Flow

• wshp_gas - Water Source Heat Pump with Gas

• pszvav_gas - Packaged Single Zone VAV with Gas

Locations

• Buffalo - Cold climate (upstate New York)

• Tampa - Hot climate (Florida)

Available Tools

Core Model Management

• initialize_model_map() - Initialize model catalog

• get_available_models() - List all available models with metadata

• get_usage_instructions() - Get comprehensive usage documentation

HTML Table Analysis

• get_html_table_by_tuple() - Retrieve specific HTML tables

• search_html_tables_by_keyword() - Find tables by keyword search

• execute_pandas_on_html_table() - Run pandas queries on HTML tables

• execute_multiline_pandas_on_html_table() - Run complex pandas code on HTML tables

Timeseries Data Analysis

• get_sql_available_hourlies() - List available hourly variables

• get_timeseries_report_by_rddid() - Extract timeseries data by RDD ID

• execute_pandas_on_timeseries() - Run pandas queries on timeseries data

• execute_multiline_pandas_on_timeseries() - Run complex pandas code on timeseries data

epJSON Model Exploration

• search_epjson_objects() - Search building model objects

• get_object_properties() - Get detailed object properties

• list_objects_by_type() - List all objects of specific type

• search_related_objects() - Find related objects by pattern

General Data Processing

• execute_query() - Execute pandas queries on cached data

• execute_multiline_query() - Execute multi-line pandas code on cached data

Quick Start Guide

1. Initialize the System

# Always start here
initialize_model_map(directory='eplus_files')

# Discover available models
models = get_available_models()

2. Explore Available Data

# Find cooling-related tables
cooling_tables = search_html_tables_by_keyword(
    id='ASHRAE901|HotelLarge|STD2025|Buffalo|gshp',
    keywords=['cooling', 'sizing', 'capacity']
)

# Get available timeseries variables
timeseries_vars = get_sql_available_hourlies(
    id='ASHRAE901|HotelLarge|STD2025|Buffalo|gshp'
)

3. Extract and Analyze Data

# Get a specific HTML table
sizing_data = get_html_table_by_tuple(
    id='ASHRAE901|HotelLarge|STD2025|Buffalo|gshp',
    query_tuple=('Entire Facility', 'HVAC Sizing Summary', 'Zone Sensible Cooling')
)

# Analyze timeseries data with pandas
energy_analysis = execute_multiline_pandas_on_timeseries(
    model_id='ASHRAE901|HotelLarge|STD2025|Buffalo|gshp',
    rddid=179,
    code='''
    # Convert energy units and calculate monthly totals
    df['kWh'] = df['Value'] / 3.6e6
    df['month'] = df['dt'].dt.month
    monthly_consumption = df.groupby('month')['kWh'].sum()
    result = monthly_consumption.to_dict()
    '''
)

Advanced Features

Pandas Integration

The server includes secure pandas execution environments for both HTML table and timeseries data:

• Single-line queries: Use execute_pandas_on_* functions

• Multi-line code: Use execute_multiline_pandas_on_* functions with result = ... pattern

• Security: Restricted execution environment prevents dangerous operations

Keyword Search

Find relevant data using flexible keyword searching:

# Search for energy consumption tables
energy_tables = search_html_tables_by_keyword(
    id=model_id,
    keywords=['energy', 'consumption', 'end use'],
    case_sensitive=False
)

Comprehensive Logging

All function calls are logged with token consumption tracking in monitor_logs/mcp_calls.log.

Performance Considerations

• Model map is cached for fast repeated access

• Large datasets are automatically truncated in responses

• HTML table search is optimized for performance

• Token consumption is monitored and logged

Error Handling

• Invalid model IDs return descriptive error messages

• Missing data returns empty results with status information

• Pandas execution errors are caught and reported safely

Token Management

The server includes comprehensive token counting and logging:

• Input/output tokens tracked per function call

• Logs stored in JSON format for analysis

• Automatic result truncation to prevent token overflow

Support

For detailed usage instructions and examples, use:

get_usage_instructions()

This returns the complete CLAUDE.md documentation file with comprehensive examples and best practices. "# eplusout-mcp"