OpenStudio MCP Server

OpenStudio MCP服务器

A. 模型上下文协议（MCP） 服务器，使克劳德等人工智能助手能够与 开放工作室 构建能源模型。通过一套可通过自然语言访问的全面工具加载、检查和操作OpenStudio模型（OSM）文件。

致谢与致谢

该项目在很大程度上基于 EnergyPlus MCP服务器 由开发 LBNL-ETA （劳伦斯伯克利国家实验室-能源技术区）。服务器架构、工具结构和实现模式已尽可能地从其出色的工作中复制出来。

此服务器中的工具是使用 OpenStudio工具包 库，它为OpenStudio的建筑建模功能提供Python接口。

该项目是在以下人员的宝贵协助下开发的 克劳德代码 由...驱动 人类学的克劳德·十四行诗4.5.

______________________________________________________________________

特性

可用工具（20+）

📁 文件和模型管理

• load_osm_model -使用智能路径解析加载OpenStudio模型文件
• save_osm_model -保存修改后的模型
• convert_to_idf -导出为EnergyPlus IDF格式
• copy_file -通过模糊匹配和智能发现复制文件
• get_model_summary -获取全面的模型统计数据
• get_building_info -获取建筑对象详细信息

📊 可视化与分析

• apply_view_model -生成交互式HTML可视化（几何图形、暖通空调、分区、材质）
• apply_space_type_and_construction_set_wizard -应用ASHRAE 90.1建筑模板

🏗️ 建筑几何

• list_spaces -列出所有具有属性的空间
• get_space_details -获取特定空间的详细信息
• list_thermal_zones -列出所有热区
• get_thermal_zone_details -获取详细的区域信息

🧱 材料和结构

• list_materials -列出所有具有热性能的材料

🌀 暖通空调系统

• list_air_loops -列出所有空气回路暖通空调系统

💡 内部载荷

• list_people_loads -列出占用负载
• list_lighting_loads -列出照明功率密度
• list_electric_equipment -列出设备负载

📅 日程表

• list_schedule_rulesets -列出所有计划规则集

⚙️ 服务器管理

• get_server_info -获取服务器配置和状态
• get_current_model_status -检查当前加载的模型

关键能力

• 智能文件发现：自动查找多个位置的文件，包括Claude Desktop上传的文件
• 模糊匹配：即使存在部分名称或拼写错误，也能查找文件
• 双重环境支持：在Docker和Claude Desktop中无缝工作
• 综合API：涵盖建筑几何形状、暖通空调、荷载、材料和明细表

______________________________________________________________________

安装

先决条件

• Docker桌面 （必需-推荐的安装方法）
• 克劳德桌面版, VS Code，或 光标 （用于AI助手集成）
• Windows/Mac/Linux 系统

快速入门（Docker-推荐）

1.克隆存储库

git clone https://github.com/roruizf/openstudio-mcp-server.git
cd openstudio-mcp-server

2.构建Docker镜像

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

这将构建一个包含以下内容的容器：

• Python 3.12
• OpenStudio 3.7.0 （使用SDK和Python绑定进行系统安装）
• 所有必需的依赖关系
• OpenStudio工具包库

验证构建：

docker images | grep openstudio-mcp-dev

3.配置克劳德桌面

编辑您的Claude Desktop配置文件：

视窗: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加此配置（Windows示例）：

{
  "mcpServers": {
    "openstudio": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "C:\\:/mnt/c",
        "-v", "C:\\PATH\\TO\\YOUR\\openstudio-mcp-server:/workspace",
        "-w", "/workspace/openstudio-mcp-server",
        "openstudio-mcp-dev",
        "uv", "run", "openstudio_mcp_server/server.py"
      ]
    }
  }
}

💡 Windows安装提示（最佳实践）： 我们强烈建议将此存储库克隆到 短根路径 喜欢 C:\openstudio-mcp-server 而不是像这样的深层用户目录 C:\Users\YourName\Documents\GitHub\openstudio-mcp-server. 为什么？ Windows的路径限制为260个字符，这可能会导致嵌套项目目录和长依赖路径的问题。此建议遵循EnergyPlus的最佳实践，以避免与路径相关的构建和运行时错误。 例子： - ✅ 推荐： C:\openstudio-mcp-server - ⚠️ 避免： C:\Users\YourName\Documents\Projects\BuildingEnergy\openstudio-mcp-server

关键： 配置需要 两个卷装 （见下文解释）：

• -v C:\\:/mnt/c -授予对C:驱动器的访问权限，以读取/写入模型文件
• -v C:\\PATH\\TO\\YOUR\\openstudio-mcp-server:/workspace -装载服务器源代码

重要：替换 C:\\PATH\\TO\\YOUR\\openstudio-mcp-server 使用您的实际存储库路径。

📁 输出目录： 生成的文件（HTML可视化、IDF导出、报告）会自动保存到 openstudio-mcp-server/outputs/ 容器内部，映射到 C:\openstudio-mcp-server\outputs\ 通过工作区卷装载在您的主机上。服务器使用适当的权限自动创建此目录。

📖 有关详细的设置说明，请参阅 CLAUDE_DESKTOP_SETUP.md

4.重新启动克劳德桌面

关闭并重新打开Claude Desktop以加载MCP服务器。

5.验证安装

在Claude Desktop中，问：

"What OpenStudio tools are available?"

Claude应该列出所有可用的工具。

______________________________________________________________________

文件访问（关键）

了解Docker卷装载

OpenStudio MCP服务器在Docker容器内运行，该容器有自己的隔离文件系统。访问您的 宿主机 （你的电脑），你必须使用 安装路径.

配置需要 两个独立的卷装，每个服务于不同的目的：

1.C：驱动器检修支架： -v C:\:/mnt/c

目的： 授予服务器 对整个C:驱动器的读/写访问权限，使其能够从主机加载模型并将输出保存到主机。

这意味着：

• 您的C:驱动器上的文件可以在以下网址访问 /mnt/c/... 路径
• 输出保存到 /mnt/c/... 在主机上保持
• 没有此装载，容器无法访问您的文件

2.服务器源代码装载： -v C:\PATH\TO\YOUR\openstudio-mcp-server:/workspace

目的： 装载服务器的 源代码 （克隆的存储库）放入容器中 /workspace，使容器能够执行Python服务器。

这意味着：

• 服务器可以访问自己的代码、依赖关系和示例文件
• 对主机上服务器代码的更改会反映在容器中
• 将占位符路径替换为实际克隆存储库的位置

如何引用文件

❌ 错误（主机路径）

C:\Users\Name\Downloads\model.osm
C:\Users\Name\Documents\output.idf

✅ 正确（容器路径）

/mnt/c/Users/Name/Downloads/model.osm
/mnt/c/Users/Name/Documents/output.idf

常见路径映射

示例用法

从下载加载模型：

User: "Load /mnt/c/Users/JohnDoe/Downloads/Office-Building.osm"

转换并保存为文档：

User: "Convert the model to IDF and save it to /mnt/c/Users/JohnDoe/Documents/Office-Building.idf"

为什么这很重要：

• ✅ 文件位于 /mnt/c/... 容器停止后路径仍然存在
• ❌ 文件保存到 /tmp/... 或 /workspace/... （无 /mnt/c)丢失

📖 有关完整的文件访问文档，请参阅 CLAUDE_DESKTOP_SETUP.md

______________________________________________________________________

用法

基本工作流程

1. 放置OSM文件 在 sample_files/models/ 目录

1. 问克劳德 使用它：

   "Load R2F-Office-Hub-006.osm and tell me about the building"

1. 克劳德将:

- 使用加载模型 load_osm_model - 使用提取信息 get_model_summary, list_spaces等等。 - 用自然语言呈现结果

对话示例

分析建筑物

You: "Load the office building model and describe its HVAC systems"

Claude will:
1. Use load_osm_model("office-building.osm")
2. Use list_air_loops()
3. Summarize the HVAC configuration

导出到EnergyPlus

You: "Convert this model to IDF format for simulation"

Claude will:
1. Use convert_to_idf()
2. Report the output file location

比较空间

You: "Which spaces have the highest lighting power density?"

Claude will:
1. Use list_spaces()
2. Use list_lighting_loads()
3. Analyze and rank the results

处理上传的文件

Claude Desktop可以处理您直接上传的文件：

1. 上传您的 .osm 聊天中的文件
2. 让克劳德分析一下
3. 服务器会自动从Claude的上传目录中查找并加载它

______________________________________________________________________

项目结构

openstudio-mcp-server/
├── openstudio_mcp_server/          # Main server package
│   ├── server.py                   # MCP tool definitions
│   ├── openstudio_manager.py       # Business logic layer
│   ├── config.py                   # Configuration management
│   └── utils/
│       ├── path_utils.py           # Intelligent path resolution
│       └── __init__.py
├── openstudio_toolkit/             # OpenStudio Python library
├── sample_files/                   # Example models
│   ├── models/                     # OSM files
│   └── weather/                    # EPW weather files
├── outputs/                        # Generated files (IDF exports, etc.)
├── logs/                           # Server logs
├── .devcontainer/
│   └── Dockerfile                  # Docker container definition
├── pyproject.toml                  # Python dependencies
├── README.md                       # This file
├── USER_GUIDE.md                   # User documentation
└── DEVELOPER_NOTES.md              # Technical documentation

______________________________________________________________________

文档

• CLAUDE_DESKTOP_SETUP.md - ⭐ Claude Desktop的金色Docker配置
• 测试\_ TOCOL.md -标准测试程序和故障排除
• 用户指南.md -面向终端用户的简单指南（包括智能路径处理）
• 开发者\_ NOTES.md -技术实施细节

______________________________________________________________________

运作原理

建筑

User (Claude Desktop)
    ↓
Claude AI (analyzes request, selects tools)
    ↓
MCP Protocol (JSON-RPC over stdin/stdout)
    ↓
FastMCP Server (server.py - tool definitions)
    ↓
OpenStudioManager (openstudio_manager.py - business logic)
    ↓
OpenStudio-Toolkit (Python wrapper functions)
    ↓
OpenStudio SDK (C++ library with Python bindings)

工具执行流程

1. 用户询问“这栋楼有多少个空间？”
2. 克劳德选择工具: list_spaces()
3. 服务器执行:

- 检查模型是否已加载 - 调用OpenStudio工具包函数 - 将空间数据提取到DataFrame中 - 转换为JSON

1. 回到克劳德: {"status": "success", "count": 12, "spaces": [...]}
2. 克劳德回应：“这栋楼有12个空间……”

______________________________________________________________________

发展

添加新工具

看 开发者\_ NOTES.md 有关以下内容的详细说明：

• 添加新的MCP工具
• 集成OpenStudio工具包功能
• 错误处理模式
• 测试程序

运行测试

# In Docker container
docker run --rm -i \
  -v "$(pwd):/workspace" \
  openstudio-mcp-dev bash -c "
  cd /workspace && uv run python -m pytest tests/
"

地方发展

# Install dependencies
uv pip install -e .

# Run server locally
uv run python -m openstudio_mcp_server.server

______________________________________________________________________

故障排除

“模型未加载”错误

• 确保您首先加载了一个模型 load_osm_model
• 检查文件是否在 sample_files/models/

“找不到文件”错误

• 验证文件路径是否正确
• 检查文件是否在已装载的工作区目录中
• 尝试仅使用文件名（服务器将自动搜索）

克劳德不使用工具

• 验证MCP服务器是否已连接（检查Claude Desktop状态栏）
• 重新启动克劳德桌面
• 检查服务器登录 logs/openstudio_mcp_server.log

Docker问题

• 确保Docker桌面正在运行
• 验证卷装载路径是否正确且绝对
• 检查Docker镜像是否已成功构建

“ModuleNotFoundError:没有名为'openstudio'的模块”错误

这意味着没有安装OpenStudio Python绑定。这不应该发生在Docker镜像上，但如果你在本地运行：

# Install OpenStudio Python package
pip install openstudio==3.7.0

# Verify installation
python -c "import openstudio; print(openstudio.openStudioVersion())"

备注Docker镜像在构建过程中会自动安装此包。

______________________________________________________________________

路线图

计划的未来增强功能：

• 模型修正：创建和修改空间、分区、曲面的工具
• 先进的暖通空调：详细的暖通空调部件检查和编辑
• 模拟：执行EnergyPlus模拟
• 结果分析：分析和可视化仿真结果
• 参数研究：自动参数分析工作流程
• 几何图形工具：从头开始创建建筑几何图形

______________________________________________________________________

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

______________________________________________________________________

许可证

MIT许可证-有关详细信息，请参阅许可证文件

______________________________________________________________________

致谢

• LBNL-ETA 作为该项目基础的EnergyPlus MCP服务器架构
• OpenStudio工具包 为OpenStudio提供Python接口
• 国家可再生能源实验室 用于开发和维护OpenStudio SDK
• Anthropic 克劳德和克劳德密码（十四行诗4.5）
• 模型上下文协议 MCP规范社区

______________________________________________________________________

支持

• 问题:
• 讨论:
• OpenStudio文档: https://openstudio.net/

______________________________________________________________________

内置于❤️ 使用Claude Code、Python和OpenStudio