Skip to content
Back to search

EnergyPlus-MCP

The first open-source Model Context Protocol server enabling AI assistants and applications to interact programmatically with EnergyPlus building energy simulation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lbnl-eta--energyplus-mcp/badge.svg)](/listings/lbnl-eta--energyplus-mcp)

HTML

<a href="/listings/lbnl-eta--energyplus-mcp"><img src="/api/listings/lbnl-eta--energyplus-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Using the MCP Server

**Prerequisites (all clients):** - [Docker Desktop](https://www.docker.com/products/docker-desktop/) (macOS / Windows) or Docker Engine (Linux), running - `git` on your PATH - The `energyplus-mcp-dev` image built locally (step 1 below — do this once)

Choose the appropriate setup for your AI assistant or IDE:

Claude Desktop

1. **Build the Docker image** (one-time setup):

   git clone https://github.com/LBNL-ETA/EnergyPlus-MCP.git
   cd EnergyPlus-MCP
   docker build -t energyplus-mcp-dev -f .devcontainer/Dockerfile .devcontainer

2. **Locate the Claude Desktop config file** for your OS: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: Claude Desktop is not officially supported on Linux. If you use a community build, check its docs for the config path (commonly `~/.config/Claude/claude_desktop_config.json`).

Create the file if it does not exist, then add:

   {
     "mcpServers": {
       "energyplus": {              // Server name shown in Claude Desktop
         "command": "docker",         // Main command to execute
         "args": [
           "run",                     // Docker subcommand to run a container
           "--rm",                    // Remove container after it exits (cleanup)
           "-i",                      // Interactive mode for stdio communication
           "-v", "/path/to/EnergyPlus-MCP:/workspace",  // Mount local dir to container
           "-w", "/workspace/energyplus-mcp-server",    // Working dir in container
           "energyplus-mcp-dev",      // Docker image name we built
           "uv", "run", "python", "-m", "energyplus_mcp_server.server"  // Server startup command
         ]
       }
     }
   }

**Important**: - Replace `/path/to/EnergyPlus-MCP` with the absolute path to your cloned repo. - macOS/Linux example: `/Users/yourname/code/EnergyPlus-MCP` - Windows example: `C:\\Users\\yourname\\code\\EnergyPlus-MCP` (use double backslashes in JSON) - Remove all comments (text after `//`) when adding to the actual config file, as JSON doesn't support comments.

3. **Restart Claude Desktop**. The EnergyPlus server should appear in the MCP servers panel.

4. **Verify**: in a new chat, ask *"List the EnergyPlus MCP tools you have access to."* You should see tools like `load_idf_model`, `run_energyplus_simulation`, `get_server_status`. If not, check [Troubleshooting](#troubleshooting).

VS Code

VS Code 1.102+ ships native MCP support. Config goes in `.vscode/mcp.json` at the workspace root (or in user settings under `"mcp"`).

1. **Build the Docker image** (same as Claude Desktop step 1 above).

2. **Create `.vscode/mcp.json`** in your project:

   {
     "servers": {
       "energyplus": {              // Server name shown in VS Code
         "command": "docker",         // Main command to execute
         "args": [
           "run",                     // Docker subcommand to run a container
           "--rm",                    // Remove container after it exits (cleanup)
           "-i",                      // Interactive mode for stdio communication
           "-v", "${workspaceFolder}:/workspace",       // Mount workspace to container
           "-w", "/workspace/energyplus-mcp-server",    // Working dir in container
           "energyplus-mcp-dev",      // Docker image name we built
           "uv", "run", "python", "-m", "energyplus_mcp_server.server"  // Server startup command
         ]
       }
     }
   }

**Important**: Remove all comments (text after `//`) when saving — JSON does not support comments.

3. **Reload VS Code** (`Ctrl/Cmd+Shift+P` → *Developer: Reload Window*). Open the Chat view and confirm the `energyplus` MCP server shows as *Running*.

4. **Verify**: ask the chat *"What EnergyPlus tools are available?"* — you should see the tool list.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 621 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # EnergyPlus MCP Server
  2. A Model Context Protocol (MCP) server that provides **35 comprehensive tools** for working with EnergyPlus building energy simulation models. This server enables AI assistants and other MCP clients to load, validate, modify, and analyze EnergyPlus IDF files through a standardized interface.
  3. > **Version**: 0.1.0
  4. > **EnergyPlus Compatibility**: 26.1.0 (default; see [Building against a different EnergyPlus version](#building-against-a-different-energyplus-version))
  5. > **Python**: 3.10+
  6. <details open>
  7. <summary><h2>📑 Table of Contents</h2></summary>
  8. - [Overview](#overview)
  9. - [Installation](#installation)
  10. - [Using the MCP Server](#using-the-mcp-server)
  11. - [Claude Desktop](#claude-desktop)
  12. - [VS Code](#vs-code)
  13. - [Cursor](#cursor)
  14. - [Development Setup](#development-setup)
  15. - [VS Code Dev Container](#vs-code-dev-container)
  16. - [Docker Setup](#docker-setup)
  17. - [Local Development](#local-development)
  18. - [Streamable HTTP Transport (Local Testing)](#streamable-http-transport-local-testing)
  19. - [Building against a different EnergyPlus version](#building-against-a-different-energyplus-version)
  20. - [Available Tools](#available-tools)
  21. - [Usage Examples](#usage-examples)
  22. - [Architecture](#architecture)
  23. - [Configuration](#configuration)
  24. - [Troubleshooting](#troubleshooting)
  25. - [Contributing](#contributing)
  26. - [Cite this work](#cite-this-work)
  27. - [License](#license)
  28. </details>
  29. ## Overview
  30. EnergyPlus MCP Server makes EnergyPlus building energy simulation accessible to AI assistants and automation tools through the Model Context Protocol.
  31. **Key Features:**
  32. - 🏗️ **Complete Model Lifecycle**: Load, validate, analyze, modify, and simulate IDF files
  33. - 🔍 **Deep Building Analysis**: Extract detailed information about zones, surfaces, materials, and schedules
  34. - 🚀 **Automated Simulation**: Execute EnergyPlus simulations with weather files
  35. - 📊 **Advanced Visualization**: Create interactive plots and HVAC system diagrams
  36. - 🔧 **HVAC Intelligence**: Discover, analyze, and visualize HVAC system topology
  37. - 📈 **Smart Output Management**: Auto-discover and configure output variables/meters
  38. ## Installation
  39. ### Using the MCP Server
  40. **Prerequisites (all clients):**
  41. - [Docker Desktop](https://www.docker.com/products/docker-desktop/) (macOS / Windows) or Docker Engine (Linux), running
  42. - `git` on your PATH
  43. - The `energyplus-mcp-dev` image built locally (step 1 below — do this once)
  44. Choose the appropriate setup for your AI assistant or IDE:
  45. #### Claude Desktop
  46. 1. **Build the Docker image** (one-time setup):
  47. ```bash
  48. git clone https://github.com/LBNL-ETA/EnergyPlus-MCP.git
  49. cd EnergyPlus-MCP
  50. docker build -t energyplus-mcp-dev -f .devcontainer/Dockerfile .devcontainer
  51. ```
  52. 2. **Locate the Claude Desktop config file** for your OS:
  53. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  54. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  55. - **Linux**: Claude Desktop is not officially supported on Linux. If you use a community build, check its docs for the config path (commonly `~/.config/Claude/claude_desktop_config.json`).
  56. Create the file if it does not exist, then add:
  57. ```json
  58. {
  59. "mcpServers": {
  60. "energyplus": { // Server name shown in Claude Desktop
  61. "command": "docker", // Main command to execute
  62. "args": [
  63. "run", // Docker subcommand to run a container
  64. "--rm", // Remove container after it exits (cleanup)
  65. "-i", // Interactive mode for stdio communication
  66. "-v", "/path/to/EnergyPlus-MCP:/workspace", // Mount local dir to container
  67. "-w", "/workspace/energyplus-mcp-server", // Working dir in container
  68. "energyplus-mcp-dev", // Docker image name we built
  69. "uv", "run", "python", "-m", "energyplus_mcp_server.server" // Server startup command
  70. ]
  71. }
  72. }
  73. }
  74. ```
  75. **Important**:
  76. - Replace `/path/to/EnergyPlus-MCP` with the absolute path to your cloned repo.
  77. - macOS/Linux example: `/Users/yourname/code/EnergyPlus-MCP`
  78. - Windows example: `C:\\Users\\yourname\\code\\EnergyPlus-MCP` (use double backslashes in JSON)
  79. - Remove all comments (text after `//`) when adding to the actual config file, as JSON doesn't support comments.
  80. 3. **Restart Claude Desktop**. The EnergyPlus server should appear in the MCP servers panel.
  81. 4. **Verify**: in a new chat, ask *"List the EnergyPlus MCP tools you have access to."* You should see tools like `load_idf_model`, `run_energyplus_simulation`, `get_server_status`. If not, check [Troubleshooting](#troubleshooting).
  82. #### VS Code
  83. VS Code 1.102+ ships native MCP support. Config goes in `.vscode/mcp.json` at the workspace root (or in user settings under `"mcp"`).
  84. 1. **Build the Docker image** (same as Claude Desktop step 1 above).
  85. 2. **Create `.vscode/mcp.json`** in your project:
  86. ```json
  87. {
  88. "servers": {
  89. "energyplus": { // Server name shown in VS Code
  90. "command": "docker", // Main command to execute
  91. "args": [
  92. "run", // Docker subcommand to run a container
  93. "--rm", // Remove container after it exits (cleanup)
  94. "-i", // Interactive mode for stdio communication
  95. "-v", "${workspaceFolder}:/workspace", // Mount workspace to container
  96. "-w", "/workspace/energyplus-mcp-server", // Working dir in container
  97. "energyplus-mcp-dev", // Docker image name we built
  98. "uv", "run", "python", "-m", "energyplus_mcp_server.server" // Server startup command
  99. ]
  100. }
  101. }
  102. }
  103. ```
  104. **Important**: Remove all comments (text after `//`) when saving — JSON does not support comments.
  105. 3. **Reload VS Code** (`Ctrl/Cmd+Shift+P` → *Developer: Reload Window*). Open the Chat view and confirm the `energyplus` MCP server shows as *Running*.
  106. 4. **Verify**: ask the chat *"What EnergyPlus tools are available?"* — you should see the tool list.
  107. #### Cursor
  108. 1. **Build the Docker image** (same as Claude Desktop step 1 above).
  109. 2. **Locate the Cursor MCP config file** for your OS:
  110. - **macOS/Linux**: `~/.cursor/mcp.json`
  111. - **Windows**: `%USERPROFILE%\.cursor\mcp.json`
  112. Create the file if it does not exist, then add:
  113. ```json
  114. {
  115. "mcpServers": {
  116. "energyplus": { // Server name shown in Cursor
  117. "command": "docker", // Main command to execute
  118. "args": [
  119. "run", // Docker subcommand to run a container
  120. "--rm", // Remove container after it exits (cleanup)
  121. "-i", // Interactive mode for stdio communication
  122. "-v", "/path/to/EnergyPlus-MCP:/workspace", // Mount local dir to container
  123. "-w", "/workspace/energyplus-mcp-server", // Working dir in container
  124. "energyplus-mcp-dev", // Docker image name we built
  125. "uv", "run", "python", "-m", "energyplus_mcp_server.server" // Server startup command
  126. ]
  127. }
  128. }
  129. }
  130. ```
  131. **Important**:
  132. - Replace `/path/to/EnergyPlus-MCP` with the absolute path to your cloned repo (Windows users: use double backslashes in JSON, e.g. `C:\\Users\\yourname\\code\\EnergyPlus-MCP`).
  133. - Remove all comments (text after `//`) when saving — JSON does not support comments.
  134. 3. **Restart Cursor**. Open *Settings → MCP* and confirm the `energyplus` server is listed as connected.
  135. 4. **Verify**: ask Cursor chat *"What EnergyPlus tools are available?"* — you should see the tool list.
  136. ### Development Setup
  137. For contributors who want to modify or extend the MCP server:
  138. #### VS Code Dev Container
  139. The easiest development setup with all dependencies pre-configured.
  140. **Prerequisites:**
  141. - [Visual Studio Code](https://code.visualstudio.com/)
  142. - [Docker Desktop](https://www.docker.com/products/docker-desktop/)
  143. - [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
  144. **Steps:**
  145. 1. Clone and open in VS Code:
  146. ```bash
  147. git clone https://github.com/LBNL-ETA/EnergyPlus-MCP.git
  148. cd EnergyPlus-MCP
  149. code .
  150. ```
  151. 2. Click "Reopen in Container" when prompted (or press `Ctrl+Shift+P` → "Dev Containers: Reopen in Container")
  152. 3. The container automatically installs EnergyPlus 26.1.0 and all dependencies (to pin a different version, see [Building against a different EnergyPlus version](#building-against-a-different-energyplus-version))
  153. #### Docker Setup
  154. For direct Docker development without VS Code:
  155. ```bash
  156. # Clone repository
  157. git clone https://github.com/LBNL-ETA/EnergyPlus-MCP.git
  158. cd EnergyPlus-MCP
  159. # Build container
  160. docker build -t energyplus-mcp-dev -f .devcontainer/Dockerfile .devcontainer
  161. # Run container
  162. docker run -it --rm -v "$(pwd)":/workspace -w /workspace/energyplus-mcp-server energyplus-mcp-dev bash
  163. # Inside container, install dependencies
  164. uv sync --extra dev
  165. ```
  166. #### Local Development
  167. For local development (requires EnergyPlus installation):
  168. **Prerequisites:**
  169. - Python 3.10+
  170. - [uv package manager](https://github.com/astral-sh/uv)
  171. - [EnergyPlus 26.1.0](https://github.com/NREL/EnergyPlus/releases/tag/v26.1.0) (or pin a different version — see [Building against a different EnergyPlus version](#building-against-a-different-energyplus-version))
  172. ```bash
  173. # Clone and install
  174. git clone https://github.com/LBNL-ETA/EnergyPlus-MCP.git
  175. cd EnergyPlus-MCP/energyplus-mcp-server
  176. uv sync --extra dev
  177. # Run server for testing
  178. uv run python -m energyplus_mcp_server.server
  179. ```
  180. #### Streamable HTTP Transport (Local Testing)
  181. By default the server runs over **stdio**, which is what every MCP client config in this README uses. The server can also run as a token-authenticated **streamable HTTP** service — useful for testing remote-style deployments, smoke-testing with `curl`, or connecting clients that expect an HTTP MCP endpoint.
  182. **Prerequisites — pick one path:**
  183. - **Docker (recommended; no local EnergyPlus install needed)**: build the `energyplus-mcp-dev` image once (per [Docker Setup](#docker-setup) above). The image ships with EnergyPlus 26.1.0 and all Python deps pre-installed.
  184. - **Local Development**: follow [Local Development](#local-development) above — Python 3.10+, `uv`, and a local EnergyPlus install. HTTP mode pulls in `uvicorn` and `python-dotenv`, which are declared in `pyproject.toml` — `uv sync --extra dev` will install them.
  185. **1. Generate a bearer token.** Tokens must be at least 32 characters:
  186. ```bash
  187. openssl rand -hex 32
  188. ```
  189. **2. Create `.env` in `energyplus-mcp-server/`** (gitignored). Copy from [.env.example](energyplus-mcp-server/.env.example) and fill in your values:
  190. ```bash
  191. # EPLUS_IDD_PATH — ONLY set this for the Local variant.
  192. # Leave it commented out / unset when using the Docker variant; the image has
  193. # EnergyPlus 26.1.0 baked in and auto-detects it. Setting a host path
  194. # (e.g. /Applications/...) inside the container will override the in-container
  195. # install and crash the server with "IDD file not found".
  196. # EPLUS_IDD_PATH=/Applications/EnergyPlus-26-1-0/Energy+.idd
  197. MCP_TRANSPORT=streamable-http
  198. MCP_HTTP_HOST=0.0.0.0
  199. MCP_HTTP_PORT=8000
  200. MCP_HTTP_PATH=/mcp
  201. # JSON array. Required when MCP_TRANSPORT=streamable-http.
  202. MCP_TOKENS=[{"label":"local-dev","token":"<paste-32+-char-hex-here>"}]
  203. ```
  204. `MCP_TOKENS` is strict (parsed in [config.py](energyplus-mcp-server/energyplus_mcp_server/config.py)):
  205. - JSON array of `{"label": "...", "token": "..."}` objects
  206. - `label` matches `[a-z0-9_-]{1,32}` (lowercase only)
  207. - `token` is at least 32 characters
  208. - Labels and tokens must be unique within the array
  209. - An empty list while `MCP_TRANSPORT=streamable-http` causes the server to refuse to start (fail-closed)
  210. **3. Start the server.** Pick the variant that matches your setup:
  211. *Docker (recommended):* publish the port, mount the repo, and let the container pick up `.env` via `--env-file`. Run from the **repo root**:
  212. ```bash
  213. docker run --rm \
  214. -p 8000:8000 \
  215. -v "$(pwd)":/workspace \
  216. -w /workspace/energyplus-mcp-server \
  217. --env-file energyplus-mcp-server/.env \
  218. energyplus-mcp-dev \
  219. uv run python -m energyplus_mcp_server.server
  220. ```
  221. > **Note**: `uv run python -m ...` outside `docker run` executes Python on your **host**, not in the container — even if the dev image is built. The container is only used when you actually invoke `docker run`. That's why the Local variant below requires a host-side EnergyPlus install.
  222. >
  223. > For the Docker command above, make sure `EPLUS_IDD_PATH` is **unset / commented out** in `.env` (see the note in step 2). `--env-file` forwards every uncommented line into the container, and a host-side `/Applications/...` path inside the container will override the image's auto-detected install and crash startup.
  224. *Local:* (requires a host EnergyPlus install matching whatever `EPLUS_IDD_PATH` is set to in `.env`)
  225. ```bash
  226. cd energyplus-mcp-server
  227. uv run python -m energyplus_mcp_server.server
  228. ```
  229. Either way you should see a log line like `Listening on http://0.0.0.0:8000 (path=/mcp, 1 tokens)`.
  230. **4. Smoke-test with curl.** The server exposes two endpoints:
  231. ```bash
  232. # Health check — no auth required, useful for confirming the server is up
  233. curl -s http://localhost:8000/health
  234. # → {"status":"ok"}
  235. # Unauthenticated MCP request — should return 401
  236. curl -i -X POST http://localhost:8000/mcp
  237. # Authenticated initialize handshake
  238. TOKEN=<paste-your-token>
  239. curl -i -X POST http://localhost:8000/mcp \
  240. -H "Authorization: Bearer $TOKEN" \
  241. -H "Content-Type: application/json" \
  242. -H "Accept: application/json, text/event-stream" \
  243. -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
  244. ```
  245. **5. Connect MCP Inspector.** Run the Inspector and point it at `http://localhost:8000/mcp` with transport `Streamable HTTP` and an `Authorization: Bearer <your-token>` header.
  246. **6. Connect an MCP client.** Replace the stdio command stanza in your client config with an HTTP one:
  247. ```json
  248. {
  249. "mcpServers": {
  250. "energyplus": {
  251. "type": "http",
  252. "url": "http://localhost:8000/mcp",
  253. "headers": { "Authorization": "Bearer <your-token>" }
  254. }
  255. }
  256. }
  257. ```
  258. **Common pitfalls:**
  259. - **`RuntimeError: IDD file not found at: /Applications/...`** when using Docker — `EPLUS_IDD_PATH` in `.env` is set to a host path and `--env-file` forwarded it into the container, overriding the image's auto-detected install. Comment out the `EPLUS_IDD_PATH` line in `.env` (or set it to the in-container path `/app/software/EnergyPlusV26-1-0/Energy+.idd`).
  260. - **`streamable-http transport requires non-empty MCP_TOKENS`** — `MCP_TOKENS` is empty or unset. Generate a token and add it to `.env`.
  261. - **JSON quoting in shells** — if you `export MCP_TOKENS=...` in zsh/bash instead of using `.env`, wrap the value in single quotes so the inner `"` characters survive.
  262. - **Port conflict on 8000** — set `MCP_HTTP_PORT=8001` in `.env` (the Cloud Run-style `PORT` env var is also honored).
  263. - **421 "Invalid Host header"** — `mcp>=1.10` ships DNS rebinding protection that rejects unrecognized Host headers. The server disables it by default for HTTP-behind-auth use cases. To re-enable with an allowlist, set `MCP_ALLOWED_HOSTS=host1.example.com,host2.example.com`.
  264. - **Tests** — transport and auth behavior is covered by `tests/test_config_transport.py` and `tests/test_auth.py`. Run with `uv run pytest tests/test_config_transport.py tests/test_auth.py`.
  265. #### Building against a different EnergyPlus version
  266. The Docker image bakes EnergyPlus **26.1.0** in by default. To pin a different release, override the build args below when building the image. You'll need:
  267. - `EPLUS_VER`: release version, e.g. `25.1.0`
  268. - `EPLUS_HASH`: the short commit string NREL embeds in the release tarball filename. Find it by looking at any asset on the release page — e.g. for [v25.1.0](https://github.com/NREL/EnergyPlus/releases/tag/v25.1.0) the tarball `EnergyPlus-25.1.0-68a4a7c774-Linux-Ubuntu22.04-x86_64.tar.gz` gives `EPLUS_HASH=68a4a7c774`.
  269. - `EPLUS_PREFIX`: install path inside the container. Must match `/app/software/EnergyPlusV<major>-<minor>-<patch>` (hyphens, not dots).
  270. - `EPLUS_DIST_SUFFIX`: Ubuntu distro tag. Use `Ubuntu22.04` for EnergyPlus ≤ 25.1.0; `Ubuntu24.04` for ≥ 26.1.0 (NREL stopped shipping 22.04 builds from 26.1.0 onward).
  271. **Example — rebuild against 25.1.0:**
  272. ```bash
  273. docker build \
  274. --build-arg EPLUS_VER=25.1.0 \
  275. --build-arg EPLUS_HASH=68a4a7c774 \
  276. --build-arg EPLUS_PREFIX=/app/software/EnergyPlusV25-1-0 \
  277. --build-arg EPLUS_DIST_SUFFIX=Ubuntu22.04 \
  278. -t energyplus-mcp-dev \
  279. -f .devcontainer/Dockerfile .devcontainer
  280. ```
  281. **Heads up — three other places reference the install path** (`/app/software/EnergyPlusV26-1-0`) and don't read the Dockerfile ARG, so if you override `EPLUS_PREFIX` you'll also need to update:
  282. - `energyplus-mcp-server/energyplus_mcp_server/config.py` — `version` and `default_installation`
  283. - `energyplus-mcp-server/.vscode/mcp.json` — the two `EnergyPlusV26-1-0` strings
  284. - The client config JSON you created for Claude Desktop / VS Code / Cursor — only if it sets `EPLUS_IDD_PATH` explicitly; otherwise `config.py`'s update is enough.
  285. Alternatively, set `EPLUS_IDD_PATH` to the new install location in your client config's `env` block — `config.py` will derive everything else from it.
  286. ## Available Tools
  287. The server provides **35 tools** organized into **5 categories**:
  288. ### 🗂️ Model Config & Loading (9 tools)
  289. - `load_idf_model` - Load and validate IDF files
  290. - `validate_idf` - Comprehensive model validation
  291. - `list_available_files` - Browse sample files and weather data
  292. - `copy_file` - Intelligent file copying with path resolution
  293. - `get_model_summary` - Extract basic model information
  294. - `check_simulation_settings` - Review simulation control settings
  295. - `modify_simulation_control` - Modify simulation parameters
  296. - `modify_run_period` - Adjust simulation time periods
  297. - `get_server_configuration` - Get server configuration info
  298. ### 🔍 Model Inspection (9 tools)
  299. - `list_zones` - List all thermal zones with properties
  300. - `get_surfaces` - Get building surface information
  301. - `get_materials` - Extract material definitions
  302. - `inspect_schedules` - Analyze all schedule objects
  303. - `inspect_people` - Analyze occupancy settings
  304. - `inspect_lights` - Analyze lighting loads
  305. - `inspect_electric_equipment` - Analyze equipment loads
  306. - `get_output_variables` - Get/discover output variables
  307. - `get_output_meters` - Get/discover energy meters
  308. ### ⚙️ Model Modification (8 tools)
  309. - `modify_people` - Update occupancy settings
  310. - `modify_lights` - Update lighting loads
  311. - `modify_electric_equipment` - Update equipment loads
  312. - `change_infiltration_by_mult` - Modify infiltration rates
  313. - `add_window_film_outside` - Add window films
  314. - `add_coating_outside` - Apply surface coatings
  315. - `add_output_variables` - Add output variables
  316. - `add_output_meters` - Add energy meters
  317. ### 🚀 Simulation & Results (4 tools)
  318. - `run_energyplus_simulation` - Execute simulations
  319. - `create_interactive_plot` - Generate HTML visualizations
  320. - `discover_hvac_loops` - Find all HVAC loops
  321. - `get_loop_topology` - Get HVAC loop details
  322. ### 🖥️ Server Management (5 tools)
  323. - `visualize_loop_diagram` - Generate HVAC diagrams
  324. - `get_server_status` - Check server health
  325. - `get_server_logs` - View recent logs
  326. - `get_error_logs` - Get error logs
  327. - `clear_logs` - Clear/rotate log files
  328. ## Usage Examples
  329. ### Basic Workflow
  330. 1. **Load a model**:
  331. ```json
  332. {
  333. "tool": "load_idf_model",
  334. "arguments": {
  335. "idf_path": "sample_files/1ZoneUncontrolled.idf"
  336. }
  337. }
  338. ```
  339. 2. **Inspect zones**:
  340. ```json
  341. {
  342. "tool": "list_zones",
  343. "arguments": {
  344. "idf_path": "sample_files/1ZoneUncontrolled.idf"
  345. }
  346. }
  347. ```
  348. 3. **Run simulation**:
  349. ```json
  350. {
  351. "tool": "run_energyplus_simulation",
  352. "arguments": {
  353. "idf_path": "sample_files/1ZoneUncontrolled.idf",
  354. "weather_file": "sample_files/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw",
  355. "annual": true
  356. }
  357. }
  358. ```
  359. 4. **Create visualization**:
  360. ```json
  361. {
  362. "tool": "create_interactive_plot",
  363. "arguments": {
  364. "output_directory": "outputs/1ZoneUncontrolled",
  365. "file_type": "variable"
  366. }
  367. }
  368. ```
  369. ### Advanced Features
  370. **HVAC System Analysis**:
  371. ```json
  372. {
  373. "tool": "discover_hvac_loops",
  374. "arguments": {
  375. "idf_path": "sample_files/5ZoneAirCooled.idf"
  376. }
  377. }
  378. ```
  379. **Generate HVAC Diagram**:
  380. ```json
  381. {
  382. "tool": "visualize_loop_diagram",
  383. "arguments": {
  384. "idf_path": "sample_files/5ZoneAirCooled.idf",
  385. "loop_name": "VAV Sys 1",
  386. "format": "png"
  387. }
  388. }
  389. ```
  390. **Discover Output Variables**:
  391. ```json
  392. {
  393. "tool": "get_output_variables",
  394. "arguments": {
  395. "idf_path": "sample_files/5ZoneAirCooled.idf",
  396. "discover_available": true,
  397. "run_days": 1
  398. }
  399. }
  400. ```
  401. ### Using with MCP Inspector
  402. Test tools interactively (requires Node.js 18+):
  403. ```bash
  404. # From the repo root, run the server inside the dev image under the Inspector
  405. npx @modelcontextprotocol/inspector \
  406. docker run --rm -i \
  407. -v "$(pwd):/workspace" \
  408. -w /workspace/energyplus-mcp-server \
  409. energyplus-mcp-dev \
  410. uv run python -m energyplus_mcp_server.server
  411. ```
  412. Or, if you have a local dev environment (see [Local Development](#local-development)):
  413. ```bash
  414. cd energyplus-mcp-server
  415. npx @modelcontextprotocol/inspector uv run python -m energyplus_mcp_server.server
  416. ```
  417. The Inspector opens a browser UI where you can list tools and invoke them with JSON arguments — useful for sanity-checking the install before wiring up a client.
  418. ## Architecture
  419. The server follows a layered architecture:
  420. ```
  421. ┌─────────────────────────┐
  422. │ MCP Protocol Layer │ FastMCP server handling client communications
  423. ├─────────────────────────┤
  424. │ Tools Layer │ 35 tools organized into 5 categories
  425. ├─────────────────────────┤
  426. │ Orchestration Layer │ EnergyPlus Manager & Config Module
  427. ├─────────────────────────┤
  428. │ EnergyPlus Integration │ Direct interface to simulation engine
  429. └─────────────────────────┘
  430. ```
  431. **Project Structure:**
  432. ```
  433. energyplus-mcp-server/
  434. ├── energyplus_mcp_server/
  435. │ ├── server.py # FastMCP server with tools
  436. │ ├── energyplus_tools.py # Core EnergyPlus integration
  437. │ ├── config.py # Configuration management
  438. │ └── utils/ # Specialized utilities
  439. ├── sample_files/ # Sample IDF and weather files
  440. ├── tests/ # Unit tests
  441. └── pyproject.toml # Dependencies
  442. ```
  443. ## Configuration
  444. The server auto-detects EnergyPlus installation and uses sensible defaults. Configuration can be customized via environment variables:
  445. - `EPLUS_IDD_PATH`: Path to EnergyPlus IDD file
  446. - `EPLUS_SAMPLE_PATH`: Custom sample files directory
  447. - `EPLUS_OUTPUT_PATH`: Output directory for results
  448. ## Troubleshooting
  449. **Common Issues:**
  450. 1. **"IDD file not found"**: Ensure EnergyPlus is installed
  451. 2. **"Module not found"**: Run `uv sync` to install dependencies
  452. 3. **"Permission denied"**: Check file permissions
  453. 4. **"Simulation failed"**: Check EnergyPlus error messages in output directory
  454. **Debugging:**
  455. - Check server status: `get_server_status`
  456. - View logs: `get_server_logs`
  457. - Check errors: `get_error_logs`
  458. ## Contributing
  459. 1. Fork the repository
  460. 2. Create a feature branch
  461. 3. Make changes with tests
  462. 4. Run checks:
  463. ```bash
  464. uv run ruff check
  465. uv run black .
  466. uv run pytest
  467. ```
  468. 5. Submit a pull request
  469. ## Cite this work
  470. If you use EnergyPlus-MCP in your research or project, please cite:
  471. > Han Li, Yujie Xu, Tianzhen Hong, EnergyPlus-MCP: A model-context-protocol server for ai-driven building energy modeling, SoftwareX, Volume 32, 2025, 102367, ISSN 2352-7110, https://doi.org/10.1016/j.softx.2025.102367.
  472. **BibTeX entry:**
  473. ```bibtex
  474. @article{li2025energyplus,
  475. title={EnergyPlus-MCP: A model-context-protocol server for ai-driven building energy modeling},
  476. author={Li, Han and Xu, Yujie and Hong, Tianzhen},
  477. journal={SoftwareX},
  478. volume={32},
  479. pages={102367},
  480. year={2025},
  481. issn={2352-7110},
  482. doi={10.1016/j.softx.2025.102367},
  483. url={https://www.sciencedirect.com/science/article/pii/S2352711025003334}
  484. }
  485. ```
  486. ## License
  487. EnergyPlus Model Context Protocol Server (EnergyPlus-MCP) Copyright (c) 2025, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.
  488. This software is distributed under a modified BSD license. See [License.txt](License.txt) for full license text and [Copyright.txt](Copyright.txt) for the copyright notice.
  489. If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Intellectual Property Office at IPO@lbl.gov.
  490. **Government Rights Notice**: This Software was developed under funding from the U.S. Department of Energy and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit others to do so.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.