EnergyPlus-MCP by LBNL-ETA - MCP Server

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
- Development Setup
Available Tools
Usage Examples
Architecture
Configuration
Troubleshooting
Contributing
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

Choose the appropriate setup for your AI assistant or IDE:

Claude Desktop

Build the Docker image (one-time setup):

git clone https://github.com/tsbyq/EnergyPlus_MCP.git
cd EnergyPlus_MCP/.devcontainer
docker build -t energyplus-mcp-dev .

Configure Claude Desktop:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "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 your actual repository path
Remove all comments (text after //) when adding to the actual config file, as JSON doesn't support comments

Restart Claude Desktop and the EnergyPlus server should connect automatically.

VS Code

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

Configure VS Code:

Add to .vscode/settings.json in your project:

{
  "mcp.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 adding to the actual config file

Restart VS Code for the changes to take effect.

Cursor

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

Configure Cursor:

Add to ~/.cursor/mcp.json:

{
  "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 your actual repository path
Remove all comments (text after //) when adding to the actual config file, as JSON doesn't support comments

Restart Cursor for the changes to take effect.

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:

Steps:

Clone and open in VS Code:

git clone https://github.com/tsbyq/EnergyPlus_MCP.git
cd EnergyPlus_MCP
code .

Click "Reopen in Container" when prompted (or press Ctrl+Shift+P → "Dev Containers: Reopen in Container")
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/tsbyq/EnergyPlus_MCP.git
cd EnergyPlus_MCP

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

# 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:

# Clone and install
git clone https://github.com/tsbyq/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

Load a model:

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

Inspect zones:

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

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
  }
}

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:

cd energyplus-mcp-server
uv run mcp-inspector energyplus_mcp_server.server

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:

"IDD file not found": Ensure EnergyPlus is installed
"Module not found": Run uv sync to install dependencies
"Permission denied": Check file permissions
"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

Fork the repository
Create a feature branch
Make changes with tests

Run checks:

uv run ruff check
uv run black .
uv run pytest

Submit a pull request

License

See file for details.