EnergyPlus MCP Server
An MCP server with 35 tools for EnergyPlus building energy models: loading IDF files, editing parameters, simulation and plots.
- 125 ★ on the repository
- Last commit
Extended access
Why this level
- The agent edits and saves IDF models in the mounted directory, and Docker gets access to that directory.
- HTTP mode opens a port; protection is limited to a bearer token.
Install
- Works in
Manual install
git clone https://github.com/LBNL-ETA/EnergyPlus-MCP.git && cd EnergyPlus-MCP && docker build -t energyplus-mcp-dev -f .devcontainer/Dockerfile .devcontainerClones the repository and builds the image with EnergyPlus once; the client then starts the server with `docker run`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent edits and saves IDF models in the mounted directory, and Docker gets access to that directory.
- HTTP mode opens a port; protection is limited to a bearer token.
This is third-party code. Review the repository files before installing.
What it does
EnergyPlus MCP Server gives an AI assistant access to building energy models in IDF format. The agent loads and validates a model, inspects zones, surfaces, materials and schedules, edits people, lighting and equipment loads, and changes the run period and simulation settings. The server runs an EnergyPlus simulation with a weather file and builds interactive HTML plots and HVAC loop diagrams. The agent adds output variables and meters and reads server logs. There are 35 tools in five groups: loading, inspection, modification, simulation and server management. The main transport is stdio, and a token-protected streamable HTTP mode exists for testing.
Who it is for. Energy engineers and researchers who simulate buildings in EnergyPlus and want to edit IDF models through Claude Desktop, VS Code or Cursor.
Good fit when
- An IDF model is examined by zones and surfaces before a run.
- Variants are compared: lighting, occupancy, infiltration, window film.
- After a run you build interactive plots for chosen variables.
- You want to see the HVAC loop diagram without parsing the IDF by hand.
Not a fit when
- Docker is unavailable: client examples run the server in a container, and the local path needs an EnergyPlus install.
- The model is not in IDF format: the server works with IDF files.
- You need another EnergyPlus version: the image targets 26.1.0 and must be rebuilt for another one.
Example request
Load the 1ZoneUncontrolled.idf model, list zones and run a simulation with a weather file.MCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
MCP_TRANSPORT- Transport: `stdio` by default or `streamable-http`.
MCP_TOKENSsecret- JSON list of bearer tokens for HTTP mode, each at least 32 characters.
Limitations
The image targets EnergyPlus 26.1.0 by default; another version is built as described in the README. Running from a client needs Docker and a locally built `energyplus-mcp-dev` image; without Docker you need Python 3.10 or newer, `uv` and an installed EnergyPlus. HTTP mode requires a bearer token of at least 32 characters in `MCP_TOKENS` and is described as local testing. The server is version 0.1.0 under a modified BSD license.
How to disable. Remove the `energyplus` entry from the MCP client configuration, then optionally run `docker rmi energyplus-mcp-dev` and delete the cloned directory.
FAQ
Which tool groups exist?
Model loading and setup, inspection, modification, simulation with plots, and server management, including `load_idf_model`, `run_energyplus_simulation`, `create_interactive_plot` and `discover_hvac_loops`.
How do I verify the connection?
Ask the client which EnergyPlus tools it has. The list should include `load_idf_model`, `run_energyplus_simulation` and `get_server_status`.
How do I run the server over HTTP?
Set `MCP_TRANSPORT=streamable-http`, `MCP_HTTP_PORT` and tokens in `MCP_TOKENS`; `openssl rand -hex 32` creates a token. The client connects to the `/mcp` path.
Is a local EnergyPlus needed?
Not when the server runs in the Docker image, which ships EnergyPlus 26.1.0. Local development installs it separately.
Can the agent edit the model?
Yes. `modify_people`, `modify_lights` and `modify_electric_equipment` change loads, `change_infiltration_by_mult` changes infiltration and `add_window_film_outside` adds window film.
Discussion
No questions or reviews yet.
Related
MCP serversOpenStudio MCP
openstudio-mcp
MCP server for building energy modeling: an agent builds an OpenStudio model, runs EnergyPlus and reads the results.
A local Microsoft MCP server for Power BI semantic models: an agent creates tables, DAX measures and relationships in Desktop, Fabric and PBIP files
MCP server and CLI to drive real Microsoft Excel: Power Query, DAX, VBA, PivotTables and charts
An MCP server with a toolbox for global briefs: markets, SEC filings, conflict, climate and news from open sources
The official MathWorks MCP server: the agent starts and quits MATLAB, writes and runs code, and checks it for errors and style
An MCP server from AntV for generating charts and diagrams: 25+ visualization types, from lines and bars to maps, mind maps and network graphs
README in short
The server works with IDF files through the standard MCP interface. Client examples run it in Docker, and development has a VS Code container and a local `uv` setup.