EnergyPlus MCP服务器
概述
此模型上下文协议（MCP）服务器通过一套丰富的工具，从EnergyPlus模型文件中发现、分析和提取数据，提供对EnergyPlus建筑能源模拟结果的全面访问。该服务器包括基于pandas的数据分析、基于关键字的表搜索以及具有令牌消费跟踪的全面日志记录等高级功能。
主要特点
- 全面的数据访问：读取epJSON输入文件、SQL结果数据库和HTML摘要报告
- 高级搜索功能：按关键字搜索HTML表，查找相关的epJSON对象，并探索模型组件
- Pandas集成：直接对时间序列和表格数据执行pandas查询
- 记录和监控：内置令牌消费跟踪和函数调用监控
- 灵活的模型发现：自动模型编目和元数据提取
安装
# Clone the repository
git clone
cd mcp-eplus-outputs
# Install dependencies
uv sync
# Run the server
uv run main.py配置
添加到您的Claude Desktop配置中：
{
"mcpServers": {
"mcp_eplus_outputs": {
"command": "uv",
"args": ["--directory", "C:/path/to/mcp-eplus-outputs", "run", "main.py"]
}
}
}文件结构
每个EnergyPlus模型由三种主要文件类型组成：
.epJSON-输入模型定义（建筑几何图形、材料、暖通空调系统、明细表）.sql-模拟结果数据库（小时时间序列数据、汇总表）.table.htm-HTML摘要报告（结果的表格摘要）
模型命名约定
文件遵循以下模式： {CODENAME}_{PROTOTYPE}_{CODEYEAR}_{CITY}_{SKIPOPTIONS}_{HVAC_LABEL}.{EXTENSION}
例子： ASHRAE901_HotelLarge_STD2025_Buffalo_SkipEC_gshp.epJSON
可用数据
建筑类型
- 酒店大型 -大型酒店建筑原型
- 仓库 -仓库建筑原型
暖通空调系统
- 地源热泵 -地源热泵
- pkgdx_gas -带气体的包装DX
- pkgdx_hp -包装式DX热泵
- pvav_awhp -带空气-水热泵的成套变风量空调
- Pvav BLR -带锅炉的成套变风量系统
- vav_ac_blr -带风冷冷水机组和锅炉的变风量
- vav_ac_blr_doas -配备风冷冷水机、锅炉和DOAS的变风量系统
- vav_wc_blr -带水冷冷水机组和锅炉的变风量
- 虚拟路由转发 -可变制冷剂流量
- wshp_gas -燃气水源热泵
- pszvav-gas -带燃气的单区VAV
位置
- 水牛 -寒冷气候（纽约州北部）
- 坦帕 -炎热气候（佛罗里达州）
可用工具
核心模型管理
initialize_model_map()-初始化模型目录get_available_models()-列出所有可用的模型及其元数据get_usage_instructions()-获取全面的使用文档
HTML表格分析
get_html_table_by_tuple()-检索特定的HTML表search_html_tables_by_keyword()-按关键字搜索查找表execute_pandas_on_html_table()-在HTML表上运行pandas查询execute_multiline_pandas_on_html_table()-在HTML表上运行复杂的pandas代码
时间序列数据分析
get_sql_available_hourlies()-列出可用的小时变量get_timeseries_report_by_rddid()-按RDD ID提取时间序列数据execute_pandas_on_timeseries()-对时间序列数据运行pandas查询execute_multiline_pandas_on_timeseries()-在时间序列数据上运行复杂的pandas代码
epJSON模型探索
search_epjson_objects()-搜索建筑模型对象get_object_properties()-获取详细的对象属性list_objects_by_type()-列出特定类型的所有对象search_related_objects()-按图案查找相关对象
一般数据处理
execute_query()-对缓存数据执行pandas查询execute_multiline_query()-对缓存数据执行多行pandas代码
快速入门指南
1.初始化系统
# Always start here
initialize_model_map(directory='eplus_files')
# Discover available models
models = get_available_models()2.探索可用数据
# Find cooling-related tables
cooling_tables = search_html_tables_by_keyword(
id='ASHRAE901|HotelLarge|STD2025|Buffalo|gshp',
keywords=['cooling', 'sizing', 'capacity']
)
# Get available timeseries variables
timeseries_vars = get_sql_available_hourlies(
id='ASHRAE901|HotelLarge|STD2025|Buffalo|gshp'
)3.提取和分析数据
# Get a specific HTML table
sizing_data = get_html_table_by_tuple(
id='ASHRAE901|HotelLarge|STD2025|Buffalo|gshp',
query_tuple=('Entire Facility', 'HVAC Sizing Summary', 'Zone Sensible Cooling')
)
# Analyze timeseries data with pandas
energy_analysis = execute_multiline_pandas_on_timeseries(
model_id='ASHRAE901|HotelLarge|STD2025|Buffalo|gshp',
rddid=179,
code='''
# Convert energy units and calculate monthly totals
df['kWh'] = df['Value'] / 3.6e6
df['month'] = df['dt'].dt.month
monthly_consumption = df.groupby('month')['kWh'].sum()
result = monthly_consumption.to_dict()
'''
)高级功能
Pandas集成
该服务器包括用于HTML表和时间序列数据的安全pandas执行环境：
- 单行查询：使用
execute_pandas_on_*函数 - 多行代码：使用
execute_multiline_pandas_on_*功能与result = ...模式 - 安全：受限的执行环境可防止危险操作
关键字搜索
使用灵活的关键字搜索查找相关数据：
# Search for energy consumption tables
energy_tables = search_html_tables_by_keyword(
id=model_id,
keywords=['energy', 'consumption', 'end use'],
case_sensitive=False
)综合录井
所有函数调用都会在中记录令牌消耗跟踪 monitor_logs/mcp_calls.log.
性能注意事项
- 模型映射已缓存，以便快速重复访问
- 大型数据集在响应中会自动截断
- HTML表搜索针对性能进行了优化
- 对令牌消耗进行监控和记录
错误处理
- 无效的模型ID返回描述性错误消息
- 缺少数据将返回带有状态信息的空结果
- Pandas执行错误被安全捕获并报告
许可证管理
服务器包括全面的令牌计数和日志记录：
- 每个函数调用跟踪的输入/输出令牌
- 以JSON格式存储的日志用于分析
- 自动截断结果以防止令牌溢出
支持
有关详细的使用说明和示例，请使用：
get_usage_instructions()这将返回完整的CLAUDE.md文档文件，其中包含全面的示例和最佳实践。 “#eplusout mcp”