EnergyPlus MCP is an MCP server for controlling EnergyPlus building energy simulation models from an AI assistant. The LBNL-ETA/EnergyPlus-MCP repository is published by the LBNL-ETA GitHub organization and describes 35 tools for loading, validating, modifying, simulating, and analyzing IDF files. In the GitHub check on August 26, 2026, the repository had 111 stars and 24 forks; the GitHub API returned NOASSERTION for license, while pyproject.toml declared BSD-3-Clause-LBNL.
For Educasium, this connector is different from drawing or mapping MCPs. It is not just for producing an image or manipulating a scene. It puts AI in front of a building simulation engine, with IDF files, weather, thermal zones, materials, schedules, internal loads, HVAC, outputs, and results. The correct editorial angle is assisted simulation with strict hypothesis checking.
Contents
- What EnergyPlus MCP does
- Installation and server lifecycle
- IDF model inspection and modification
- Simulation, results, and visualization
- HTTP authentication and operational limits
- Comparison with Mapbox and QGIS
- Educasium position
What EnergyPlus MCP Does
Key point: EnergyPlus MCP gives an AI assistant 35 tools for the lifecycle of an EnergyPlus model, from reading the IDF file to plotting results. The README lists EnergyPlus 26.1.0 as the default compatibility target and Python 3.10 or newer.
An MCP for building simulation
EnergyPlus is used to simulate building energy performance. The MCP server makes this work accessible through conversation, but it does not change the professional nature of the analysis. Model assumptions, weather, schedules, internal loads, materials, and systems remain decisive.
The README groups capabilities into loading and configuration, inspection, modification, simulation, and server management. The examples show a simple flow: load an IDF file, inspect zones, run a simulation with an EPW weather file, then create an interactive visualization.
Why it is sensitive
An energy simulation can produce numbers that look very precise. Displayed precision is not proof that the model is correct. If the IDF is incomplete, the weather file does not match the site, occupancy schedules are wrong, or HVAC is poorly modeled, the result can mislead.
That nuance avoids promising automatic energy audits. EnergyPlus MCP is a manipulation and exploration assistant. Validation still belongs to simulation methodology, applicable standards, and the responsible professional.
Installation And Server Lifecycle
Key point: the recommended path uses Docker, a local energyplus-mcp-dev image, and a Python server launched from energyplus-mcp-server. The README provides configurations for Claude Desktop, VS Code, and Cursor.
Documented prerequisites
The README lists Docker Desktop or Docker Engine, git, and a locally built Docker image. The basic flow clones the repository, builds the image from .devcontainer/Dockerfile, then configures the MCP client to run docker with a repository mount, /workspace/energyplus-mcp-server as working directory, and uv run python -m energyplus_mcp_server.server.
The verified pyproject in energyplus-mcp-server lists energyplus-mcp-server 0.1.0, Python >=3.10, and dependencies including mcp[cli] >=1.10, eppy, matplotlib, networkx, pandas, plotly, graphviz, uvicorn[standard], and python-dotenv. The README also allows local development if EnergyPlus is installed on the host.
Practical lifecycle
The lifecycle is heavier than a simple MCP. You need to build the image, mount the right folder, verify the EnergyPlus path, choose the transport, and start the server. The README highlights a Docker pitfall: do not pass a host-side EPLUS_IDD_PATH into the container if that path does not exist inside the image.
For training, this should be prepared before the session. Docker failure, badly escaped Windows paths, or a missing image can consume the workshop. The first checks should be server status, available files, then loading a sample IDF.
IDF Model Inspection And Modification
Key point: the tools cover reading, validation, summary, zones, surfaces, materials, schedules, internal loads, and targeted modifications. That is valuable for learning the model, but risky without copies.
Model inspection
The README tool list includes load_idf_model, validate_idf, list_available_files, copy_file, get_model_summary, check_simulation_settings, and get_server_configuration under loading and configuration. Inspection covers list_zones, get_surfaces, get_materials, inspect_schedules, inspect_people, inspect_lights, inspect_electric_equipment, get_output_variables, and get_output_meters.
This enables a useful teaching exercise: ask the assistant to summarize a model, identify thermal zones, check surfaces, explain occupancy schedules, and detect requested outputs. The learner sees that simulation begins before pressing run: it begins by understanding the model.
Possible modifications
The README announces modification tools such as modify_people, modify_lights, modify_electric_equipment, change_infiltration_by_mult, add_window_film_outside, add_coating_outside, add_output_variables, and add_output_meters. The code check also found close internal functions for people, lights, and electric equipment inspection and modification.
Use these tools on copies. Changing occupancy, lighting, or equipment loads directly changes results. Adding window film or an exterior coating can be useful for scenario comparison, but physical properties and assumptions must be documented.
Simulation, Results, And Visualization
Key point: EnergyPlus MCP can run simulations with weather, discover HVAC loops, produce topology views, and create interactive plots. This is where the connector becomes useful for comparing scenarios.
Running and reading a simulation
The README documents run_energyplus_simulation with an IDF file, weather file, and annual option in its examples. The simulation produces an output directory that result tools can read. Execution depends on EnergyPlus, weather files, paths, and write permissions.
Variable and meter tools can discover or add outputs. This is essential: a simulation does not automatically produce the answer you need if outputs are not configured. The assistant can help request the right variables, but the user must understand what they measure.
HVAC and plots
The README lists discover_hvac_loops, get_loop_topology, and visualize_loop_diagram. pyproject includes networkx, graphviz, and plotly, which fit graph and visualization work. create_interactive_plot generates HTML visualizations from results.
For Educasium, a good example would compare two simple scenarios: baseline infiltration versus reduced infiltration, or baseline glazing versus window film. The exercise should show modified files, weather, simulation period, tracked variables, and produced plots.
HTTP Authentication And Operational Limits
Key point: stdio is the default mode, but the server can run over streamable HTTP with bearer tokens of at least 32 characters and fail-closed startup when tokens are absent. That is meaningful security behavior.
HTTP mode
The README documents MCP_TRANSPORT=streamable-http, MCP_HTTP_HOST, MCP_HTTP_PORT, MCP_HTTP_PATH, and MCP_TOKENS. Tokens must be a JSON list of label and token objects. Labels follow a short lowercase format, tokens must be unique, and an empty list in HTTP mode prevents startup.
That is healthy behavior: exposing a simulation server over HTTP without authentication would be a bad idea. Even locally, users need to know who can reach the port, where files are mounted, and which paths the container can read or write.
Limits to state
EnergyPlus MCP does not replace a national regulatory engine or certification workflow. The README cites EnergyPlus 26.1.0 by default, but also explains how to rebuild for another version. That means the engine version is part of the result.
An Educasium workflow asks readers to document EnergyPlus version, IDF, EPW, period, outputs, modifications, and runtime environment. Without that journal, two results are difficult to compare.
Comparison With Mapbox And QGIS
Key point: EnergyPlus MCP works on building model performance; Mapbox MCP works on location; QGIS MCP works on geographic layers. They can appear in one study workflow, but they answer different levels.
| Need | EnergyPlus MCP | QGIS MCP | Mapbox MCP |
|---|---|---|---|
| Load and validate an IDF | Strong fit | Out of scope | Out of scope |
| Modify loads, schedules, or outputs | Strong fit | Out of scope | Out of scope |
| Produce an accessibility map | Out of scope | Fit | Strong fit |
| Cross zoning and constraints | Out of scope | Strong fit | Limited |
| Compare energy scenarios | Strong fit | Possible context | Site context |
Logical order
Mapbox can help locate a project and understand accessibility. QGIS can consolidate territorial constraints and context layers. EnergyPlus enters when a building model exists and the question concerns consumption, comfort, internal loads, envelope, or systems.
This order prevents asking EnergyPlus MCP for things it does not do, such as finding an address, and asking Mapbox for things it does not do, such as simulating a thermal zone.
Educasium Position
Key point: Educasium presents EnergyPlus MCP as a simulation workflow accelerator, not a generator of energy truth. Serious use depends on assumptions, versions, and validation.
What to teach
A useful workshop starts with a sample file from the repository. The assistant lists files, loads an IDF, validates the model, summarizes zones and materials, checks simulation settings, runs a short simulation, then creates a plot. Only then does the learner modify one simple assumption on a copy and compare results.
The pedagogy should force traceability. Every scenario needs a name, a precise modification, a weather file, a period, and a list of outputs. Without that, AI can accelerate confusion instead of analysis.
Editorial position
The LBNL-ETA source and the SoftwareX publication cited in the README give the project weight. The difference between GitHub's detected license field and the license declared in pyproject remains visible, because that double check avoids simplifying facts to make the page more commercial.