Energy Plus MCP

EnergyPlus MCP服务器

一种模型上下文协议（MCP）服务器，提供 35个综合工具 组织成 5大类 用于使用EnergyPlus构建能源模拟模型。该服务器使AI助手和其他MCP客户端能够通过标准化的接口加载、验证、修改和分析EnergyPlus IDF（输入数据文件）模型。

版本: 0.1.0\ EnergyPlus兼容性: 25.1.0\ python: 3.10+

这个回购是关于什么的？

此存储库包含一个专门为EnergyPlus建筑能源模拟工作流程设计的MCP服务器。EnergyPlus是一个功能强大的建筑能源模拟引擎，这个MCP服务器使人工智能助手和自动化工具可以访问它。

主要特点：

• 🏗️ 完整的模型生命周期：加载、验证、分析、修改和模拟EnergyPlus IDF文件
• 🔍 深层建筑分析：提取有关分区、曲面、材质、构造和明细表的详细信息
• ⚙️ 柔性仿真控制：配置仿真参数、运行周期和输出要求
• 🚀 自动模拟：使用天气文件和后处理执行完整的EnergyPlus模拟
• 📊 高级可视化：创建交互式HTML绘图和HVAC系统图
• 🔧 暖通空调系统智能：暖通空调回路的全面发现、拓扑分析和可视化
• 📈 智能输出管理：输出变量和仪表的智能发现和配置
• 🎯 建筑改造：用于修改渗透、添加窗膜、表面涂层等的工具
• 📋 日程智能：对所有EnergyPlus计划类型进行深入分析和修改
• 🖥️ 企业就绪：内置日志记录、错误跟踪、运行状况监视和调试功能
• 📁 智能文件管理：智能路径解析、模糊文件匹配和有组织的示例库

建筑

EnergyPlus MCP服务器遵循分层架构，关注点明确分离：

• MCP协议层：FastMCP服务器处理客户端通信
• 工具层：35个工具分为5个功能类别
• 业务流程层：EnergyPlus管理器和核心配置模块，用于工作流协调
• EnergyPlus集成层：与EnergyPlus仿真引擎和文件系统的直接接口

该架构实现了与AI助手、IDE和其他MCP客户端的可扩展集成，同时保持了强大的错误处理和企业级日志记录功能。

可用工具

EnergyPlus MCP服务器提供 35个综合工具 组织成 5大类 如架构图所示：

🗂️ 模型配置和加载 （9个工具）

• copy_file -具有路径解析和模糊匹配的智能文件复制
• load_idf_model -加载并验证EnergyPlus IDF文件，并提供详细的错误报告
• list_available_files -浏览示例文件、示例文件和天气数据
• get_model_summary -提取基本模型信息（建筑、场地、仿真控制、版本）
• validate_idf -带有警告和错误的全面模型验证
• check_simulation_settings -查看当前模拟控制和运行周期设置
• modify_simulation_control -修改模拟控制参数（运行周期、大小等）
• modify_run_period -调整模拟时间段和日期
• get_server_configuration -获取详细的服务器配置和版本信息

🔍 模型检查 （9个工具）

• list_zones -列出所有具有详细属性的热区
• get_surfaces -获取全面的建筑表面信息和几何图形
• get_materials -提取材料和结构定义
• inspect_schedules -使用值提取支持对所有进度对象进行深入分析
• inspect_people -对人员对象进行详细分析，包括占用计算和热舒适设置
• inspect_lights -通过功率计算和热分数对Lights对象进行综合分析
• inspect_electric_equipment -用功率计算和热分数对电气设备对象进行综合分析
• get_output_variables -获取已配置的变量或发现所有可用的输出变量
• get_output_meters -获取已配置的电表或查找所有可用的电表

⚙️ 模型修正 （8工具）

• modify_people -使用灵活的目标（全部、按区域或按名称）修改People对象
• modify_lights -修改支持不同计算方法的灯光对象
• modify_electric_equipment -修改支持不同计算方法的ElectricEquipment对象
• change_infiltration_by_mult -通过乘法因子修改渗透速率
• add_window_film_outside -为具有自定义特性的外部玻璃添加窗膜
• add_coating_outside -涂覆具有热性能的外表面涂层（墙壁/屋顶）
• add_output_variables -添加具有智能验证和格式化功能的输出变量
• add_output_meters -添加具有灵活规格格式的输出仪表

🚀 模拟与结果 （4个工具）

• run_energyplus_simulation -使用天气文件执行完整的EnergyPlus模拟
• create_interactive_plot -根据模拟结果生成交互式HTML图
• discover_hvac_loops -发现模型中的所有暖通空调回路（设备、冷凝器、空气）
• get_loop_topology -获取特定暖通空调回路及其组件和连接的详细拓扑结构

🖥️ 服务器管理和日志记录 （5个工具）

• visualize_loop_diagram -生成暖通空调系统拓扑和流路的可视化图
• get_server_status -检查服务器运行状况、性能和系统信息
• get_server_logs -检索最近的服务器日志条目以进行调试
• get_error_logs -获取最近的错误日志条目以进行故障排除
• clear_logs -通过自动备份清除/轮换当前日志文件

项目结构

• sample_files/：EnergyPlus IDF文件和天气数据示例

- 1ZoneUncontrolled.idf：简单的单区模型 - 1ZoneEvapCooler.idf：单区蒸发冷却 - 5ZoneAirCooled.idf：多区域风冷型号 - USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw：旧金山的天气文件

• energyplus_mcp_server/：服务器实现

- server.py：配备所有可用工具的FastMCP服务器 - energyplus_tools.py：EnergyPlus文件操作实用程序

• config.py：配置管理

• utils/：高级实用模块

- schedules.py：全面的时间表解析、分析和修改实用程序 - diagrams.py：暖通空调图生成和可视化工具

• pyproject.toml：项目元数据和依赖关系

• outputs/：模拟输出和修改文件目录

安装说明

选项1:VS代码开发容器（推荐）

最简单的入门方法是使用VS Code-dev容器，它提供了一个预安装了EnergyPlus的完全配置的环境。

先决条件：

• Visual Studio Code
• 开发容器扩展

步骤：

1. 克隆存储库：

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

1. 在VS代码中打开：

   code .

1. 出现提示时，单击“在容器中重新打开”或：

- 按 Ctrl+Shift+P - 选择“开发容器：在容器中重新打开”

1. 容器将自动：

- 安装EnergyPlus 25.1.0 - 设置Python依赖关系 uv - 配置开发环境 - 为Python和EnergyPlus安装VS代码扩展 - 跑 uv sync --extra dev 安装所有依赖项

Dev容器中包含的内容：

• 预配置环境：基于Ubuntu的容器，包含所有依赖项
• EnergyPlus集成：EnergyPlus 25.1.0预安装和配置
• Python环境：Python 3.11+ uv 包管理器
• VS代码扩展：Python、Jupyter、EnergyPlus ModelKit和TOML支持
• 端口转发：MCP检查器（6274）、HTTP服务器（8080、3000）的自动转发
• 工作区设置：正确的工作区文件夹配置和Python解释器路径

开发容器设置在中定义 .devcontainer/ 文件夹包含：

• Dockerfile：带有EnergyPlus和Python设置的容器映像
• devcontainer.json：VS代码配置、扩展和端口转发

选项2：普通Docker

如果你更喜欢直接使用Docker而不使用VS代码：

先决条件：

步骤：

1. 克隆存储库：

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

1. 构建开发容器：

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

1. 运行带有卷装载的容器：

   docker run -it --rm -v "%cd%":/workspace -w /workspace/energyplus-mcp-server energyplus-mcp-dev bash

1. 在容器内部，安装依赖项：

   uv sync --extra dev

方案3：地方发展

对于没有容器的本地开发（需要手动安装EnergyPlus）：

先决条件：

• Python 3.10或更高版本
• uv包管理器
• EnergyPlus 25.1.0（下载自 )

步骤：

1. 克隆并导航到服务器目录：

   git clone https://github.com/tsbyq/EnergyPlus_MCP.git
   cd EnergyPlus_MCP\energyplus-mcp-server

1. 安装依赖项：

   uv sync --extra dev

1. 在您的环境或配置文件中配置EnergyPlus路径（服务器将在标准安装位置查找EnergyPlus）。

如何使用

EnergyPlus MCP服务器可以根据您的需求以多种方式使用：

1.作为人工智能助理的MCP服务器

主要用例是将服务器连接到MCP兼容的AI助手（如Claude Desktop、VS Code Copilot或其他MCP客户端）。

启动服务器：

cd energyplus-mcp-server
uv run python -m energyplus_mcp_server.server

服务器将以STDIO模式启动，并可以连接到MCP客户端。

MCP客户端配置示例 （适用于克劳德桌面）：

{
  "mcpServers": {
    "energyplus": {
      "command": "uv",
      "args": ["run", "python", "-m", "energyplus_mcp_server.server"],
      "cwd": "/path/to/energyplus-mcp-server"
    }
  }
}

2.交互式开发和测试

使用MCP检查器 （如有）：

uv run mcp-inspector energyplus_mcp_server.server

这将打开一个web界面，用于交互式测试MCP工具。

直接使用Python：

# In a Python environment or Jupyter notebook
from energyplus_mcp_server.energyplus_tools import EnergyPlusManager

ep_manager = EnergyPlusManager()

# Load a sample model
result = ep_manager.load_idf("1ZoneUncontrolled.idf")
print(result)

# Get model summary
summary = ep_manager.get_model_basics("1ZoneUncontrolled.idf")
print(summary)

3.常用示例

加载并验证IDF文件：

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

修改模拟设置：

{
  "tool": "modify_simulation_control",
  "arguments": {
    "idf_path": "sample_files/1ZoneUncontrolled.idf",
    "field_updates": {
      "Run_Simulation_for_Weather_File_Run_Periods": "Yes",
      "Do_Zone_Sizing_Calculation": "Yes"
    },
    "output_path": "outputs/modified_model.idf"
  }
}

列出模型中的分区：

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

检查模型中的明细表：

{
  "tool": "inspect_schedules",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf",
    "include_values": true
  }
}

修改渗透速率：

{
  "tool": "change_infiltration_by_mult",
  "arguments": {
    "idf_path": "sample_files/1ZoneUncontrolled.idf",
    "mult": 0.5,
    "output_path": "outputs/reduced_infiltration.idf"
  }
}

将窗膜添加到外表面：

{
  "tool": "add_window_film_outside",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf",
    "u_value": 3.5,
    "shgc": 0.35,
    "visible_transmittance": 0.60,
    "output_path": "outputs/with_window_film.idf"
  }
}

为外表面添加涂层：

{
  "tool": "add_coating_outside",
  "arguments": {
    "idf_path": "sample_files/1ZoneUncontrolled.idf",
    "location": "Wall",
    "solar_abs": 0.3,
    "thermal_abs": 0.8,
    "output_path": "outputs/with_coating.idf"
  }
}

获取可用的示例文件：

{
  "tool": "list_sample_files",
  "arguments": {}
}

获取配置的输出变量：

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

发现所有可用的输出变量：

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

获取配置的输出仪表：

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

发现所有可用的输出仪表：

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

发现暖通空调回路：

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

可视化暖通空调回路图：

{
  "tool": "visualize_loop_diagram",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf",
    "loop_name": "Hot Water Loop",
    "output_path": "outputs/hvac_diagram.png",
    "format": "png"
  }
}

运行EnergyPlus模拟：

{
  "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,
    "readvars": true
  }
}

根据模拟结果创建交互式绘图：

{
  "tool": "create_interactive_plot",
  "arguments": {
    "output_directory": "outputs/1ZoneUncontrolled",
    "file_type": "auto",
    "custom_title": "Zone Temperature Analysis"
  }
}

获取服务器日志以进行调试：

{
  "tool": "get_server_logs",
  "arguments": {
    "lines": 100
  }
}

4.暖通空调系统分析与可视化

该服务器提供高级暖通空调系统分析功能，具有拓扑检测和可视化图表生成功能：

暖通空调分析特征：

• 循环发现：自动发现所有暖通空调回路（工厂、冷凝器、空气回路）
• 拓扑映射：通过供需侧分析提取详细的组件级拓扑
• 成分检测：识别风扇、盘管、泵、风道末端、区域设备和连接
• 直观图：生成暖通空调系统流路和连接的PNG/SVG图
• 节点跟踪：遵循整个系统的空气/水节点连接

暖通空调系统分析示例：

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

获取特定回路的详细拓扑结构：

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

生成可视化图表：

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

5.高级进度分析

该服务器通过 inspect_schedules 工具和底层 schedules.py 公用设施：

支持的计划类型：

• Schedule:Constant：单值明细表
• Schedule:Day:Hourly：24小时每日时间表
• Schedule:Day:Interval：基于时间间隔的每日时间表
• Schedule:Day:List：具有自定义时间步长的基于列表的计划
• Schedule:Compact：复杂的多时段时间表
• Schedule:Year, Schedule:Week:*：结构明细表参考

进度分析功能：

• 从所有支持的类型中解析和提取实际计划值
• 计算统计数据（最小值、最大值、平均值）
• 进度修改的自然语言解析（开发中）
• 不同EnergyPlus类型之间的计划格式转换
• 全面的验证和错误检查

进度检查示例：

{
  "tool": "inspect_schedules",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf",
    "include_values": true
  }
}

这将返回有关所有计划的详细信息，包括其类型、参考和实际时间值数据。

6.智能输出管理

服务器提供具有自动发现功能的智能输出变量和仪表管理：

输出变量发现：

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

添加带有验证的输出变量：

{
  "tool": "add_output_variables",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf",
    "variables": [
      "Zone Air Temperature",
      ["Zone Air Relative Humidity", "hourly"],
      {"key_value": "*", "variable_name": "Surface Inside Face Temperature", "frequency": "daily"}
    ],
    "validation_level": "moderate"
  }
}

7.文件路径处理

服务器支持灵活的文件路径解析：

• 绝对路径：直接文件系统路径
• 相对路径：相对于sample_files目录
• 仅限文件名：首先在sample_files目录中搜索
• 输出路径：默认情况下，修改后的文件保存到输出目录

示例：

"1ZoneUncontrolled.idf"                    → sample_files/1ZoneUncontrolled.idf
"sample_files/1ZoneUncontrolled.idf"       → sample_files/1ZoneUncontrolled.idf
"/absolute/path/to/model.idf"              → /absolute/path/to/model.idf
"C:\\Users\\MyUser\\Documents\\model.idf"  → C:\Users\MyUser\Documents\model.idf

8.完整的仿真工作流程

服务器支持完整的建筑能源模拟工作流程：

步骤1：加载并验证模型

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

步骤2：修改模拟设置（可选）

{
  "tool": "modify_simulation_control",
  "arguments": {
    "idf_path": "sample_files/1ZoneUncontrolled.idf",
    "field_updates": {
      "Do_Zone_Sizing_Calculation": "Yes",
      "Do_System_Sizing_Calculation": "Yes"
    },
    "output_path": "outputs/modified_model.idf"
  }
}

步骤3：运行模拟

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

步骤4：创建交互式可视化

{
  "tool": "create_interactive_plot",
  "arguments": {
    "output_directory": "outputs/modified_model",
    "file_type": "variable",
    "custom_title": "Annual Energy Performance"
  }
}

9.服务器管理和调试

服务器包括全面的日志记录和调试工具：

监控服务器运行状况：

{
  "tool": "get_server_status",
  "arguments": {}
}

查看最近的活动：

{
  "tool": "get_server_logs",
  "arguments": {
    "lines": 50
  }
}

检查错误：

{
  "tool": "get_error_logs",
  "arguments": {
    "lines": 20
  }
}

可用工具参考

依赖项

此项目使用 uv 用于快速依赖管理。所有依赖关系都在中定义 pyproject.toml:

核心依赖关系

• mcp[cli]：使用CLI工具的模型上下文协议框架
• eppy：用于IDF文件操作的EnergyPlus Python库
• matplotlib：用于生成暖通空调回路图的绘图库
• plotly：用于从模拟结果创建HTML可视化的交互式绘图库
• pandas：用于处理EnergyPlus输出文件的数据分析库
• networkx：暖通空调拓扑可视化的图形分析库
• graphviz：用于生成复杂网络图的图形可视化库

开发依赖项（随附安装 --extra dev)

• ipykernel：Jupyter笔记本内核支持
• pytest：测试框架
• pytest-cov：测试覆盖率报告
• pytest-asyncio：异步测试支持
• black：代码格式
• ruff：快速Python linter和格式化程序
• mypy：静态类型检查

系统依赖关系（在开发容器中）

• EnergyPlus 25.1.0：建筑能源模拟引擎
• Node.js 20：用于MCP检查员和基于网络的工具
• Python 3.12：运行时环境

配置

服务器使用可以通过环境变量或配置文件进行自定义的配置系统。关键配置区域：

• EnergyPlus路径：IDD文件位置、可执行路径、版本
• 文件路径：示例文件、输出目录、临时文件
• 服务器设置：名称、版本、调试模式
• 日志记录：级别和格式配置

默认配置在开发容器环境中开箱即用。

故障排除

常见问题：

1. “找不到IDD文件”：确保EnergyPlus安装正确，IDD路径已配置
2. “导入错误：eppy”：运行 uv sync 安装依赖项
3. “权限被拒绝”：确保输入/输出目录的文件权限正确
4. “IDF文件无效”：使用EnergyPlus验证工具检查IDF语法
5. “模拟失败”：检查结果目录中的仿真输出文件是否有EnergyPlus错误消息
6. “绘图创建失败”：确保模拟输出存在并包含有效数据

调试模式： 集 debug_mode: true 在配置中或使用环境变量启用详细日志记录。

获取帮助：

• 检查服务器状态：使用 get_server_status 工具
• 查看最近的日志：使用 get_server_logs 工具
• 检查错误：使用 get_error_logs 工具
• 验证配置：使用 get_server_configuration 工具
• 示例文件：使用 list_sample_files 查看可用的测试文件
• 如果需要，清除日志：使用 clear_logs 旋转日志文件的工具

贡献

1. 分叉存储库
2. 创建要素分支
3. 通过适当的测试进行更改
4. 运行linting： uv run ruff check
5. 运行格式化： uv run black .
6. 运行测试： uv run pytest
7. 提交拉取请求

许可证

看 许可证 文件以获取详细信息。