OpenStudio MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with OpenStudio building energy models. Load, inspect, and manipulate OpenStudio Model (OSM) files through a comprehensive set of tools accessible via natural language.

Credits and Acknowledgments

This project is heavily based on the EnergyPlus MCP Server developed by LBNL-ETA (Lawrence Berkeley National Laboratory - Energy Technologies Area). The server architecture, tool structure, and implementation patterns have been replicated as closely as possible from their excellent work.

The tools in this server are built using the OpenStudio-Toolkit library, which provides Python interfaces to OpenStudio's building modeling capabilities.

This project was developed with the invaluable assistance of Claude Code powered by Anthropic's Claude Sonnet 4.5.

Features

Available Tools (20+)

📁 File & Model Management

• load_osm_model - Load OpenStudio Model files with intelligent path resolution
• save_osm_model - Save modified models
• convert_to_idf - Export to EnergyPlus IDF format
• copy_file - Copy files with fuzzy matching and smart discovery
• get_model_summary - Get comprehensive model statistics
• get_building_info - Get building object details

📊 Visualization & Analysis

• apply_view_model - Generate interactive HTML visualization (geometry, HVAC, zones, materials)
• apply_space_type_and_construction_set_wizard - Apply ASHRAE 90.1 building templates

🏗️ Building Geometry

• list_spaces - List all spaces with properties
• get_space_details - Get detailed information about a specific space
• list_thermal_zones - List all thermal zones
• get_thermal_zone_details - Get detailed zone information

🧱 Materials & Constructions

• list_materials - List all materials with thermal properties

🌀 HVAC Systems

• list_air_loops - List all air loop HVAC systems

💡 Internal Loads

• list_people_loads - List occupancy loads
• list_lighting_loads - List lighting power densities
• list_electric_equipment - List equipment loads

📅 Schedules

• list_schedule_rulesets - List all schedule rulesets

⚙️ Server Management

• get_server_info - Get server configuration and status
• get_current_model_status - Check currently loaded model

Key Capabilities

• Intelligent File Discovery: Automatically finds files in multiple locations including Claude Desktop uploads
• Fuzzy Matching: Finds files even with partial names or typos
• Dual Environment Support: Works seamlessly in both Docker and Claude Desktop
• Comprehensive API: Covers building geometry, HVAC, loads, materials, and schedules

Installation

Prerequisites

• Docker Desktop (REQUIRED - recommended installation method)
• Claude Desktop, VS Code, or Cursor (for AI assistant integration)
• Windows/Mac/Linux system

Quick Start (Docker - Recommended)

1. Clone the Repository

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

2. Build Docker Image

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

This builds a container with:

• Python 3.12
• OpenStudio 3.7.0 (system installation with SDK and Python bindings)
• All required dependencies
• OpenStudio-Toolkit library

Verify Build:

docker images | grep openstudio-mcp-dev

3. Configure Claude Desktop

Edit your Claude Desktop configuration file:

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

Add this configuration (Windows example):

{
  "mcpServers": {
    "openstudio": {
      "command": "docker",
      "args": [


... [View full README on GitHub](https://github.com/roruizf/openstudio-mcp-server#readme)