EnergyPlus MCP

November, 2025

Last month, I attended a webinar hosted by ASHRAE TC 4.7 about EnergyPlus-MCP, the first open-source Model Context Protocol (MCP) server designed for EnergyPlus simulation workflows. The Model Context Protocol (MCP) is an open-source standard that defines a standardized, uniform way for Large Language Models (LLMs) and other AI systems to utilize external applications and data sources. Following an introduction by Tianzhen Hong, Han Li provided a compelling presentation and demonstration of the server's capabilities. Their work, co-authored with Yuijie Xu, is detailed in their paper published in the December issue of SoftwareX.

The EnergyPlus MCP repository contains a development container that can be opened using Docker Desktop and VSCode with the Dev Containers extension. Once that software is installed, opening the repository in VS Code will prompt the user to reopen it in a container. After accepting, Docker Desktop will build the container with all the relevant software and tools pre-installed.

EnergyPlus MCP setup: building the container in VSCode
EnergyPlus MCP setup: building the container in VSCode (2x speed, edited).

The user can then interact with the EnergyPlus MCP server via LLM prompts in GitHub Copilot. The workspace includes a sample_files directory with several EnergyPlus models for quick testing. We can prompt the LLM to list the files in sample_files:

List files in sample_files
List the files in sample_files.

The LLM simply listed all the files in the sample_files folder using basic filesystem operations, without utilizing any specialized capabilities provided by the EnergyPlus MCP server. The EnergyPlus MCP contains a Python Class called EnergyPlusManager, which consists of several methods that facilitate EnergyPlus input file operations and automate simulation workflows. Some of these are generic helper methods for working with file systems and post-processing, such as:

  • _find_simulation_outputs
  • _resolve_idf_path
  • _resolve_weather_file_path
  • copy_file
  • create_interactive_plot
  • get_configuration_info
  • list_available_files

Most of the methods in EnergyPlusManager involve reading and modifying EnergyPlus input data files (IDFs), such as:

  • _create_simplified_diagram
  • _create_topology_based_diagram
  • _get_airloop_topology
  • _get_branch_details
  • _get_branches_from_list
  • _get_connector_details
  • _get_connectors_from_list
  • _get_plant_condenser_topology
  • add_coating_outside
  • add_output_meters
  • add_output_variables
  • add_window_film_outside
  • change_infiltration_by_mult
  • check_simulation_settings
  • discover_hvac_loops
  • get_loop_topology
  • get_materials
  • get_model_basics
  • get_output_meters
  • get_output_variables
  • get_surfaces
  • inspect_electric_equipment
  • inspect_lights
  • inspect_people
  • inspect_schedules
  • list_zones
  • load_idf
  • modify_electric_equipment
  • modify_lights
  • modify_people
  • modify_simulation_settings
  • run_simulation
  • validate_idf
  • visualize_loop_diagram

These domain-specific methods rely on eppy for parsing, manipulating, and writing EnergyPlus IDF files. Eppy (EnergyPlus PYthon) is an open-source scripting library for IDFs developed by Santosh Philip.

In addition to the sample_files folder, the dev container provides access to example files from the EnergyPlus installation (/app/software/EnergyPlusV25-1-0/ExampleFiles/). We can prompt the LLM to list and summarize the example files:

Example files are summarized using the list_available_files tool
Example files are summarized using the list_available_files tool.

This time, the LLM used the list_available_files tool to list the example files. We can also ask more specific questions, like “Which models have VAV systems?”:

Models with VAV systems
The LLM lists models with VAV systems.

The MCP server utilizes FastMCP to register tool functions using the @mcp.tool() decorator. These tool functions act as wrappers that call methods from the EnergyPlusManager class to perform EnergyPlus operations. For example, this code shows how the change_infiltration_by_mult tool is registered in server.py using the @mcp.tool() decorator.

The registered tool functions are necessary to provide capabilities that the LLM cannot perform on its. Modern LLMs are already very capable of understanding concepts, generating code, and providing instructions. In fact, changing the infiltration is a simple enough task that the LLM may try to perform this request without using any registered tools:

LLM changes infiltration without using registered tools
The LLM changes the infiltration rate without using any registered tools.

Rather than hoping the LLM will implement this task correctly on its own, we can instead prompt the LLM to use the change_infiltration_by_mult method:

LLM changes infiltration using change_infiltration_by_mult
The LLM changes the infiltration rate using change_infiltration_by_mult.

If we want to avoid the LLM altogether but still utilize the methods available in EnergyPlusManager, we can always write a script to call these methods the old-fashioned way. Calling the methods directly in a script ensures that we perform the correct operations and is much faster once the script is developed. The obvious downside to this approach is that more time and attention are needed to develop the script, call it with the appropriate arguments, and process the results (if needed). For example, if we want to halve the infiltration rate in an IDF, we can apply the change_infiltration_by_mult method with a mult_factor of 0.5:

mult_factor = 0.5 manager = EnergyPlusManager(config) manager.change_infiltration_by_mult( idf_path=idf_path, mult=mult_factor, output_path=output_path )

The true power of the LLM lies in its capacity for intelligent workflow orchestration. Instead of requiring a step-by-step procedure, the model needs only a single, high-level instruction to autonomously select, sequence, and execute the necessary tools to achieve the final goal. For example, we can prompt: "Copy an office model from ExampleFiles to sample_files, add window film to reduce solar heat gain, run a simulation, and tell me the energy impact," and the LLM will orchestrate the appropriate tools to complete the entire workflow.

The LLM performs a list of tasks using registered tools.

Based on a single-sentence prompt, the LLM:

  • Ran list_available_files to discover the available IDFs
  • Found models that resemble office buildings
  • Copied the ASHRAE 90.1-2019 Medium Office prototype to sample_files (using copy_file)
  • Ran add_window_film_outside to apply the window film measure to all 18 window surfaces in the model
  • Added appropriate output meters to the model (add_output_meters) to the modified model and the original model
  • Discovered the appropriate weather file given the location in the IDF (Denver, CO)
  • Created a temporary directory for the simulations (create_directory)
  • Ran simulations of the modified and original models (run_energyplus_simulation)
  • Read the output files (read_text_file), and summarized the results
  • Presented a succinct summary of the analysis, pointing out that the window film measure actually increased energy consumption due to increasing the window SHGC (0.45 vs 0.38 baseline), which caused an increase in cooling energy relative to the baseline model.

The EnergyPlus MCP server demonstrates how the Model Context Protocol can bridge the gap between natural language instructions and complex building energy simulation workflows. By combining the reasoning capabilities of modern LLMs with domain-specific tools, this approach offers a compelling alternative to traditional scripting — one that balances automation with precision. While writing custom scripts provides full control and predictability, the MCP approach excels at exploratory analysis and rapid prototyping, where the ability to express intent in plain language can significantly accelerate the discovery process. As MCP adoption grows and more building simulation tools become accessible through this standard interface, we can expect to see new possibilities for integrating AI into engineering workflows, making sophisticated analyses more accessible without sacrificing technical rigor.