eplusout-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@eplusout-mcp get HVAC sizing summary for HotelLarge Buffalo gshp"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.pyConfiguration
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 catalogget_available_models()- List all available models with metadataget_usage_instructions()- Get comprehensive usage documentation
HTML Table Analysis
get_html_table_by_tuple()- Retrieve specific HTML tablessearch_html_tables_by_keyword()- Find tables by keyword searchexecute_pandas_on_html_table()- Run pandas queries on HTML tablesexecute_multiline_pandas_on_html_table()- Run complex pandas code on HTML tables
Timeseries Data Analysis
get_sql_available_hourlies()- List available hourly variablesget_timeseries_report_by_rddid()- Extract timeseries data by RDD IDexecute_pandas_on_timeseries()- Run pandas queries on timeseries dataexecute_multiline_pandas_on_timeseries()- Run complex pandas code on timeseries data
epJSON Model Exploration
search_epjson_objects()- Search building model objectsget_object_properties()- Get detailed object propertieslist_objects_by_type()- List all objects of specific typesearch_related_objects()- Find related objects by pattern
General Data Processing
execute_query()- Execute pandas queries on cached dataexecute_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_*functionsMulti-line code: Use
execute_multiline_pandas_on_*functions withresult = ...patternSecurity: 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"
Available Tools
19 toolsexecute_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
Scored across 19 tools
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.
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.
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.
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
Related MCP Connectors
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
EnergyPlus weather files (EPW, DDY, STAT) and design conditions for any site, OpenStudio-MCP ready.
Browse and query the EIA API v2 — electricity, petroleum, natural gas, coal, forecasts via MCP.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables querying and retrieving materials data from the Materials Project via MCP tools, supporting search, lookup, comparison, and export.1-
- FlicenseNot gradedqualityDmaintenanceIntegrates 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.-
- FlicenseNot gradedqualityCmaintenanceEnables reading, normalizing, validating, merging, and exporting data from Excel, CSV, JSON, and SQLite sources into a unified schema, with tools exposed via FastMCP.1-

idfkit-mcpofficial
AlicenseAqualityBmaintenanceEnables AI assistants to create, edit, and simulate EnergyPlus building energy models via natural language. Supports schema exploration, model editing, simulation execution, and documentation search.39237 PyPI14MIT