Skip to main content
Glama
eplusout-mcp

eplusout-mcp

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

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"

Available Tools

19 tools
execute_multiline_pandas_on_html_tableA

Execute multi-line pandas code on HTML table data from an EnergyPlus model.

Retrieves an HTML table and executes multi-line pandas code on it. The dataframe is available as 'df' in your code. Use 'result = ...' to return values.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models). query_tuple: A tuple containing (zone/component, report_name, table_name) to identify the table. code: Multi-line Python code to execute

Returns: String representation of the result or execution status.

Examples: # Complex table analysis code = ''' # Convert numeric columns numeric_cols = df.select_dtypes(include=[np.number]).columns df_numeric = df[numeric_cols]

# Calculate totals and percentages
totals = df_numeric.sum()
percentages = (df_numeric / totals) * 100

result = percentages
'''
execute_multiline_pandas_on_html_table(model_id, query_tuple, code)

Inputs: id (required), code (required), query_tuple (required). Returns: result

execute_multiline_pandas_on_timeseriesA

Execute multi-line pandas code on timeseries data from an EnergyPlus model.

Retrieves timeseries data for a specific variable and executes multi-line pandas code on it. The dataframe is available as 'df' in your code. Use 'result = ...' to return values.

Args: model_id: The model_id of the EnergyPlus model (obtain from get_available_models). rddid: List of RDD IDs for the desired variables (obtain from get_sql_available_hourlies). code: Multi-line Python code to execute

Returns: String representation of the result or execution status.

Examples: # Complex analysis with multiple steps code = ''' df['hour'] = df['dt'].dt.hour df['month'] = df['dt'].dt.month monthly_peaks = df.groupby('month')['Value'].max() result = monthly_peaks ''' execute_multiline_pandas_on_timeseries(model_id, rddid, code)

Inputs: code (required), rddid (required), model_id (required). Returns: result

execute_multiline_queryA

Execute multi-line pandas operations on the cached DataFrame.

Args: file_hash (str): Hash of the loaded parquet file to query. query (str): Multi-line Python code to execute.

Returns: str: Formatted result or status message.

Notes: Does not accept import statements or print statements.

Inputs: query (required), file_hash (required). Returns: result

execute_pandas_on_html_tableA

Execute pandas operations on HTML table data from an EnergyPlus model.

Retrieves an HTML table and executes pandas operations on it. The dataframe is available as 'df' in your query.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models). query_tuple: A tuple containing (zone/component, report_name, table_name) to identify the table. query: Pandas query to execute (e.g., "df.describe()", "df.sum()")

Returns: String representation of the query result with formatted output.

Examples: # Get summary statistics execute_pandas_on_html_table(model_id, query_tuple, "df.describe()")

# Find maximum values
execute_pandas_on_html_table(model_id, query_tuple, "df.max()")

# Filter data
execute_pandas_on_html_table(model_id, query_tuple, "df[df > 1000]")

Inputs: id (required), query (required), query_tuple (required). Returns: result

execute_pandas_on_timeseriesA

Execute pandas operations on timeseries data from an EnergyPlus model.

Retrieves timeseries data for a specific variable and executes pandas operations on it. The dataframe is available as 'df' in your query.

Args: model_id: The model_id of the EnergyPlus model (obtain from get_available_models). rddid: A list of RDD IDs for the desired variable (obtain from get_sql_available_hourlies). query: Pandas query to execute (e.g., "df.describe()", "df['Value'].mean()")

Returns: String representation of the query result with formatted output.

Examples: # Get basic statistics execute_pandas_on_timeseries(model_id, rddid, "df.describe()")

# Get hourly averages by month
execute_pandas_on_timeseries(model_id, rddid, "df.groupby(df['dt'].dt.month)['Value'].mean()")

# Find peak values
execute_pandas_on_timeseries(model_id, rddid, "df.loc[df['Value'].idxmax()]")

Inputs: query (required), rddid (required), model_id (required). Returns: result

execute_queryC

Execute a pandas query on the cached DataFrame.

Args: file_hash (str): Hash of the loaded parquet file to query. query (str): The pandas query to execute.

Returns: str: Formatted result of the query.

Inputs: query (required), file_hash (required). Returns: result

get_available_modelsA

Retrieve all available EnergyPlus models and their metadata.

Returns detailed information about all discovered EnergyPlus models, including their unique identifiers for use with other tools.

Args: directory: Directory parameter (currently ignored, uses default directory).

Returns: List of dictionaries containing model information: - model_id: Unique identifier for use with other tools - codename: Model standard (e.g., 'ASHRAE901') - prototype: Building type (e.g., 'HotelLarge', 'Warehouse') - codeyear: Code year (e.g., 'STD2025') - city: Location (e.g., 'Buffalo', 'Tampa') - label: HVAC system type (e.g., 'gshp', 'vav_ac_blr') - file paths for epJSON, SQL, and HTML files

Inputs: directory.

get_error_fileA

Retrieve a specific Error file from an EnergyPlus model using ID. Useful in debugging.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models).

Returns: Plain text output of EPlus error file

Inputs: id (required). Returns: result

get_html_table_by_tupleA

Retrieve a specific HTML table from an EnergyPlus model using a tuple query.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models). query_tuple: A tuple containing (zone/component, report_name, table_name) to identify the specific table to retrieve.

Returns: JSON string containing the requested table data with columns and rows.

Inputs: id (required), query_tuple (required). Returns: result

get_object_propertiesC

Get detailed properties of a specific EnergyPlus object.

Retrieves all properties and values for a specific object in the epJSON model, providing complete configuration details for analysis.

Args: model_id: The model_id of the EnergyPlus model object_type: EnergyPlus object type object_name: Specific object name

Returns: Dictionary containing: - object_type: The EnergyPlus object type - object_name: The specific object name - properties: All object properties and their values - property_count: Number of properties - model_id: The model identifier

Inputs: model_id (required), object_name (required), object_type (required).

get_rdd_fileA

Retrieve a specific RDD file from an EnergyPlus model using ID. Useful in debugging.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models).

Returns: Plain text output of RDD file, which shows available output reports.

Inputs: id (required). Returns: result

get_sql_available_hourliesA

List available hourly timeseries variables in the SQL output for a specific model.

Discovers all hourly timeseries data available in a model's SQL output database, providing variable names and RDD IDs needed to extract specific timeseries data.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models).

Returns: Available hourly timeseries variables including: - Variable names (e.g., 'Zone Air Temperature', 'HVAC Electric Power') - RDD IDs for use with get_timeseries_report_by_rddid - Units and key values for each variable

Inputs: id (required). Returns: result

get_timeseries_report_by_rddid_listA

Retrieve hourly timeseries data for a specific variable from an EnergyPlus model.

Extracts complete hourly timeseries data for a specific variable using its RDD (Report Data Dictionary) ID, providing timestamped values for analysis.

Args: model_id: The model_id of the EnergyPlus model (obtain from get_available_models). rddid: A list of RDD IDs (integers) for the desired variables (obtain from get_sql_available_hourlies).

Returns: List of timestamped records, each containing: - dt: Timestamp for the data point - Value: Numeric value for the variable - Name: Variable name (e.g., 'Zone Air Temperature') - KeyValue: Zone or component identifier - Units: Units of measurement

Example: First use get_sql_available_hourlies to find the RDD ID for 'Zone Air Temperature', then use that ID with this tool.

Inputs: rddid (required), model_id (required).

get_usage_instructionsA

Get comprehensive usage instructions for the EnergyPlus MCP server.

Returns detailed documentation about how to use all available tools, including workflow guidance, data structures, and best practices.

Returns: Complete usage instructions and documentation for the MCP server.

Inputs: no named parameters. Returns: result

initialize_model_mapA

Initialize or refresh the model map cache for EnergyPlus models.

Scans a directory for EnergyPlus model files (.epJSON, .sql, .htm) and creates a cached model map for efficient access. Call this first before accessing model data.

Args: directory: Directory containing EnergyPlus model files. Defaults to 'DEFUALT_DIRECTORY'.

Returns: Status message confirming successful initialization.

Inputs: directory. Returns: result

list_objects_by_typeB

List all objects of a specific type in the epJSON model.

Retrieves all objects of a specified EnergyPlus object type, providing an overview of all components of that type in the building model.

Args: model_id: The model_id of the EnergyPlus model object_type: EnergyPlus object type to list

Returns: Dictionary containing: - object_type: The requested object type - object_count: Number of objects found - objects: All objects of the specified type with their properties - model_id: The model identifier

Inputs: model_id (required), object_type (required).

search_epjson_objectsA

Search for specific objects in epJSON data structure.

Searches through the epJSON model data to find objects matching the specified criteria. Useful for finding specific components, systems, or zones within the building model.

Args: model_id: The model_id of the EnergyPlus model object_type: Specific EnergyPlus object type (e.g., "Coil:Cooling:WaterToAirHeatPump:EquationFit") object_name: Specific object name (e.g., "ROOM_1_FLR_3 COOLING COIL") search_pattern: Pattern to search for in object names (e.g., "ROOM_1_FLR_3") case_sensitive: Whether to perform case-sensitive search

Returns: Dictionary containing: - search_results: Matching objects organized by type - search_criteria: The search parameters used - search_stats: Statistics about the search results

Inputs: model_id (required), object_name, object_type, case_sensitive, +1 more.

search_html_tables_by_keywordA

Search for HTML tables containing specific keywords in their names.

Filters available HTML tables based on keyword matches in table names, report names, or other metadata. Useful for finding specific types of tables like 'cooling', 'heating', 'energy', etc.

Args: id: The model_id of the EnergyPlus model (obtain from get_available_models). keywords: List of keywords to search for (e.g., ['cooling', 'coil', 'capacity']) case_sensitive: Whether to perform case-sensitive search (default: False)

Returns: Dictionary containing: - matching_tables: List of tables that match the keywords - search_keywords: The keywords that were searched for - total_matches: Number of matching tables found - search_stats: Statistics about the search - model_id: The model identifier

Examples: # Find cooling-related tables search_html_tables_by_keyword(model_id, ['cooling', 'coil'])

# Find energy consumption tables
search_html_tables_by_keyword(model_id, ['energy', 'consumption'])

# Case-sensitive search for specific terms
search_html_tables_by_keyword(model_id, ['DX', 'VAV'], case_sensitive=True)

Common Keyword Categories:

Energy & Consumption: ['energy', 'consumption', 'end use', 'site energy', 'source energy', 'electricity', 'natural gas', 'fuel', 'annual', 'monthly', 'utility', 'cost', 'performance']

Cooling Systems: ['cooling', 'coil', 'capacity', 'chiller', 'dx cooling', 'sensible cooling', 'latent cooling', 'peak cooling', 'cooling tower', 'evaporative cooler', 'refrigeration']

Heating Systems: ['heating', 'boiler', 'heat pump', 'heating coil', 'heat recovery', 'sensible heating', 'peak heating', 'furnace', 'baseboard', 'radiant heating', 'heat exchanger']

HVAC Components: ['fan', 'pump', 'air loop', 'plant loop', 'zone equipment', 'terminal unit', 'ahu', 'air handler', 'vav', 'cav']

Building Envelope: ['window', 'wall', 'roof', 'floor', 'construction', 'material', 'thermal bridge', 'infiltration', 'ventilation']

Lighting & Equipment: ['lighting', 'electric equipment', 'gas equipment', 'occupancy', 'schedule', 'internal load', 'plug load']

Inputs: id (required), keywords (required), case_sensitive.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 19 tools

    Disambiguation2/5

    Multiple tools have unclear boundaries: search_epjson_objects and search_related_objects both search by pattern, and execute_query/execute_multiline_query overlap heavily with the pandas-on-timeseries/html-table variants. The generic execute_query tools also have an ambiguous data source (file_hash) with no tool to obtain it, making them easy to confuse with the model-specific query tools.

    Naming Consistency4/5

    All tool names use snake_case and mostly follow a verb_noun pattern (get_, search_, list_, execute_). Minor deviations exist, such as get_timeseries_report_by_rddid_list placing 'list' at the end and get_sql_available_hourlies using an awkward adjective order, but the overall convention is predictable.

    Tool Count3/5

    With 19 tools, the set falls in the borderline heavy range. Several tools are near-duplicates (single-line vs multi-line query variants, and multiple pandas-execution tools), inflating the count beyond what the core domain requires. A leaner set of 12-15 tools would be more coherent.

    Completeness3/5

    The core domain of EnergyPlus model exploration, HTML table retrieval, timeseries extraction, and epJSON object inspection is largely covered. However, execute_query and execute_multiline_query are dead ends because no tool exposes how to obtain a file_hash, and there is no way to enumerate all HTML tables without knowing keywords. These gaps will cause agent confusion.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Integrates multiple XRPL data sources including LOS, Validator History Service, XRPL JSON-RPC, and XRPLMeta to provide comprehensive querying of XRPL network data, accounts, transactions, tokens, validators, and more via MCP tools.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables reading, normalizing, validating, merging, and exporting data from Excel, CSV, JSON, and SQLite sources into a unified schema, with tools exposed via FastMCP.
      1
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to create, edit, and simulate EnergyPlus building energy models via natural language. Supports schema exploration, model editing, simulation execution, and documentation search.
      39
      237 PyPI
      14
      MIT