EnergyPlus MCP Server

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.

Version: 0.1.0
EnergyPlus Compatibility: 25.1.0
Python: 3.10+

📑 Table of Contents

• Overview
• Installation
  • Using the MCP Server
    • Claude Desktop
    • VS Code
    • Cursor
  • Development Setup
    • VS Code Dev Container
    • Docker Setup
    • Local Development
• Available Tools
• Usage Examples
• Architecture
• Configuration
• Troubleshooting
• Contributing
• Cite this work
• License

Overview

EnergyPlus MCP Server makes EnergyPlus building energy simulation accessible to AI assistants and automation tools through the Model Context Protocol.

Key Features:

• 🏗️ Complete Model Lifecycle: Load, validate, analyze, modify, and simulate IDF files
• 🔍 Deep Building Analysis: Extract detailed information about zones, surfaces, materials, and schedules
• 🚀 Automated Simulation: Execute EnergyPlus simulations with weather files
• 📊 Advanced Visualization: Create interactive plots and HVAC system diagrams
• 🔧 HVAC Intelligence: Discover, analyze, and visualize HVAC system topology
• 📈 Smart Output Management: Auto-discover and configure output variables/meters

Installation

Using the MCP Server

Prerequisites (all clients):

• 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.

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.

Cursor

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

2. Locate the Cursor MCP config file for your OS:

   • macOS/Linux: ~/.cursor/mcp.json
   • Windows: %USERPROFILE%\.cursor\mcp.json

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

   {
     "mcpServers": {
       "energyplus": {              // Server name shown in Cursor
         "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 (Windows users: use double backslashes in JSON, e.g. C:\\Users\\yourname\\code\\EnergyPlus-MCP).
   • Remove all comments (text after //) when saving — JSON does not support comments.

3. Restart Cursor. Open Settings → MCP and confirm the energyplus server is listed as connected.

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

Development Setup

For contributors who want to modify or extend the MCP server:

VS Code Dev Container

The easiest development setup with all dependencies pre-configured.

Prerequisites:

• Visual Studio Code
• Docker Desktop
• Dev Containers extension

Steps:

1. Clone and open in VS Code:

   git clone https://github.com/LBNL-ETA/EnergyPlus-MCP.git
   cd EnergyPlus-MCP
   code .

2. Click "Reopen in Container" when prompted (or press Ctrl+Shift+P → "Dev Containers: Reopen in Container")

3. The container automatically installs EnergyPlus 25.1.0 and all dependencies

Docker Setup

For direct Docker development without VS Code:

# Clone repository
git clone https://github.com/LBNL-ETA/EnergyPlus-MCP.git
cd EnergyPlus-MCP

# Build container
docker build -t energyplus-mcp-dev -f .devcontainer/Dockerfile .devcontainer

# Run container
docker run -it --rm -v "$(pwd)":/workspace -w /workspace/energyplus-mcp-server energyplus-mcp-dev bash

# Inside container, install dependencies
uv sync --extra dev

Local Development

For local development (requires EnergyPlus installation):

Prerequisites:

• Python 3.10+
• uv package manager
• EnergyPlus 25.1.0

# Clone and install
git clone https://github.com/LBNL-ETA/EnergyPlus-MCP.git
cd EnergyPlus-MCP/energyplus-mcp-server
uv sync --extra dev

# Run server for testing
uv run python -m energyplus_mcp_server.server

Available Tools

The server provides 35 tools organized into 5 categories:

🗂️ Model Config & Loading (9 tools)

• load_idf_model - Load and validate IDF files
• validate_idf - Comprehensive model validation
• list_available_files - Browse sample files and weather data
• copy_file - Intelligent file copying with path resolution
• get_model_summary - Extract basic model information
• check_simulation_settings - Review simulation control settings
• modify_simulation_control - Modify simulation parameters
• modify_run_period - Adjust simulation time periods
• get_server_configuration - Get server configuration info

🔍 Model Inspection (9 tools)

• list_zones - List all thermal zones with properties
• get_surfaces - Get building surface information
• get_materials - Extract material definitions
• inspect_schedules - Analyze all schedule objects
• inspect_people - Analyze occupancy settings
• inspect_lights - Analyze lighting loads
• inspect_electric_equipment - Analyze equipment loads
• get_output_variables - Get/discover output variables
• get_output_meters - Get/discover energy meters

⚙️ Model Modification (8 tools)

• modify_people - Update occupancy settings
• modify_lights - Update lighting loads
• modify_electric_equipment - Update equipment loads
• change_infiltration_by_mult - Modify infiltration rates
• add_window_film_outside - Add window films
• add_coating_outside - Apply surface coatings
• add_output_variables - Add output variables
• add_output_meters - Add energy meters

🚀 Simulation & Results (4 tools)

• run_energyplus_simulation - Execute simulations
• create_interactive_plot - Generate HTML visualizations
• discover_hvac_loops - Find all HVAC loops
• get_loop_topology - Get HVAC loop details

🖥️ Server Management (5 tools)

• visualize_loop_diagram - Generate HVAC diagrams
• get_server_status - Check server health
• get_server_logs - View recent logs
• get_error_logs - Get error logs
• clear_logs - Clear/rotate log files

Usage Examples

Basic Workflow

1. Load a model:

   {
     "tool": "load_idf_model",
     "arguments": {
       "idf_path": "sample_files/1ZoneUncontrolled.idf"
     }
   }

2. Inspect zones:

   {
     "tool": "list_zones",
     "arguments": {
       "idf_path": "sample_files/1ZoneUncontrolled.idf"
     }
   }

3. Run simulation:

   {
     "tool": "run_energyplus_simulation",
     "arguments": {
       "idf_path": "sample_files/1ZoneUncontrolled.idf",
       "weather_file": "sample_files/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw",
       "annual": true
     }
   }

4. Create visualization:

   {
     "tool": "create_interactive_plot",
     "arguments": {
       "output_directory": "outputs/1ZoneUncontrolled",
       "file_type": "variable"
     }
   }

Advanced Features

HVAC System Analysis:

{
  "tool": "discover_hvac_loops",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf"
  }
}

Generate HVAC Diagram:

{
  "tool": "visualize_loop_diagram",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf",
    "loop_name": "VAV Sys 1",
    "format": "png"
  }
}

Discover Output Variables:

{
  "tool": "get_output_variables",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf",
    "discover_available": true,
    "run_days": 1
  }
}

Using with MCP Inspector

Test tools interactively (requires Node.js 18+):

# From the repo root, run the server inside the dev image under the Inspector
npx @modelcontextprotocol/inspector \
  docker run --rm -i \
    -v "$(pwd):/workspace" \
    -w /workspace/energyplus-mcp-server \
    energyplus-mcp-dev \
    uv run python -m energyplus_mcp_server.server

Or, if you have a local dev environment (see Local Development):

cd energyplus-mcp-server
npx @modelcontextprotocol/inspector uv run python -m energyplus_mcp_server.server

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.

Architecture

The server follows a layered architecture:

┌─────────────────────────┐
│   MCP Protocol Layer    │  FastMCP server handling client communications
├─────────────────────────┤
│     Tools Layer         │  35 tools organized into 5 categories
├─────────────────────────┤
│  Orchestration Layer    │  EnergyPlus Manager & Config Module
├─────────────────────────┤
│  EnergyPlus Integration │  Direct interface to simulation engine
└─────────────────────────┘

Project Structure:

energyplus-mcp-server/
├── energyplus_mcp_server/
│   ├── server.py              # FastMCP server with tools
│   ├── energyplus_tools.py    # Core EnergyPlus integration
│   ├── config.py              # Configuration management
│   └── utils/                 # Specialized utilities
├── sample_files/              # Sample IDF and weather files
├── tests/                     # Unit tests
└── pyproject.toml            # Dependencies

Configuration

The server auto-detects EnergyPlus installation and uses sensible defaults. Configuration can be customized via environment variables:

• EPLUS_IDD_PATH: Path to EnergyPlus IDD file
• EPLUS_SAMPLE_PATH: Custom sample files directory
• EPLUS_OUTPUT_PATH: Output directory for results

Troubleshooting

Common Issues:

1. "IDD file not found": Ensure EnergyPlus is installed
2. "Module not found": Run uv sync to install dependencies
3. "Permission denied": Check file permissions
4. "Simulation failed": Check EnergyPlus error messages in output directory

Debugging:

• Check server status: get_server_status
• View logs: get_server_logs
• Check errors: get_error_logs

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run checks:

   uv run ruff check
   uv run black .
   uv run pytest

5. Submit a pull request

Cite this work

If you use EnergyPlus-MCP in your research or project, please cite:

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.

BibTeX entry:

@article{li2025energyplus,
  title={EnergyPlus-MCP: A model-context-protocol server for ai-driven building energy modeling},
  author={Li, Han and Xu, Yujie and Hong, Tianzhen},
  journal={SoftwareX},
  volume={32},
  pages={102367},
  year={2025},
  issn={2352-7110},
  doi={10.1016/j.softx.2025.102367},
  url={https://www.sciencedirect.com/science/article/pii/S2352711025003334}
}

License

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.

This software is distributed under a modified BSD license. See License.txt for full license text and Copyright.txt for the copyright notice.

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.

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.