EnergyPlus

EnergyPlus MCP Server exposes a suite of 35 tools for working with EnergyPlus IDF models through the MCP interface. The server is designed to load, validate, analyze, modify, and simulate EnergyPlus IDF files, enabling AI assistants and automation tools to interact with building energy models in a structured way. Tools are organized into categories such as loading and validating models, inspecting model contents (zones, surfaces, materials, schedules), managing simulation settings, and generating outputs for visualization or further analysis. Typical workflows include loading an IDF, validating it for consistency, querying model metadata, adjusting run periods or weather associations, and kicking off EnergyPlus simulations to obtain results for visualization or optimization tasks.

Prerequisites:

• Python 3.10+
• EnergyPlus 25.1.0 installed on your system (or accessible within the development environment)
• uv (uv package manager) installed
• Docker (for docker-based setup) if you plan to run the container workflow

Local development (recommended):

1. Clone the repository: git clone https://github.com/tsbyq/EnergyPlus_MCP.git cd EnergyPlus_MCP/energyplus-mcp-server

2. Install dependencies via uv (in a suitable Python environment): uv sync --extra dev

3. Run the MCP server locally for testing: uv run python -m energyplus_mcp_server.server

Container-based development (Docker):

1. Build the development image (from repo root): docker build -t energyplus-mcp-dev -f .devcontainer/Dockerfile .

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

3. Inside the container, install dev dependencies and start the server: uv sync --extra dev uv run python -m energyplus_mcp_server.server

Notes:

• Adjust paths to your local repository when using docker-based commands (e.g., /path/to/EnergyPlus-MCP).
• Ensure EnergyPlus 25.1.0 and Python 3.10+ are available in the development environment if running outside Docker.

Tips and notes:

• The MCP server exposes 35 tools organized into categories such as Model Config & Loading, Validation, File Management, and Analysis/Output generation.
• If using Docker-based configuration in IDEs (Claude Desktop, VS Code, Cursor), ensure the mounted workspace and working directory match your project layout for smooth communication with the server.
• For local development, you may need to run EnergyPlus separately or rely on the container environment where EnergyPlus is pre-installed.
• If you encounter connectivity issues between the MCP client and server, verify the command, working directory, and volume mounts in your mcp configuration.
• When sharing this server configuration, replace placeholder paths (like /path/to/EnergyPlus-MCP) with actual paths on the host system.
• The EnergyPlus compatibility note in the README indicates supported EnergyPlus versions; ensure compatibility when requesting simulations or analyzing outputs.