Skip to content

NatLabRockies/openstudio-mcp

Repository files navigation

openstudio-mcp

MCP Badge

Model Context Protocol (MCP) server for OpenStudio building energy simulation. Enables LLMs and MCP hosts (Claude Desktop, Cursor, Claude Code, etc.) to create, query, and modify OpenStudio models, run EnergyPlus simulations, and inspect results — all through natural language.

23 skills • 142 tools • 6 prompts • 4 resources • 480+ integration tests


What Can It Do?

Ask your AI assistant to do things like:

  • "Create a 10-zone office building with VAV reheat and run an annual simulation"
  • "What's the EUI? Show me the unmet heating hours."
  • "Switch the HVAC from VAV to VRF heat pumps and compare energy use"
  • "Add R-30 roof insulation and see how it affects the cooling load"
  • "Build two adjacent zones from floor plans, match the shared wall, add 40% south glazing"
  • "Write a custom measure to set all lights to 8 W/m2, test it, apply it, and compare the EUI"
  • "Apply the AEDG Small Office measure from my local measures directory"

The server handles all the OpenStudio/EnergyPlus complexity behind MCP tool calls.


Quick Start

Prerequisites

  • Docker Desktop installed and running (download)
  • An MCP host — an AI application that can connect to MCP tool servers. Claude Desktop is the recommended starting point.

Step 1: Clone & Build

git clone https://github.com/NatLabRockies/openstudio-mcp.git
cd openstudio-mcp
docker build -t openstudio-mcp:dev -f docker/Dockerfile .

Step 2: Configure Claude Desktop

Open your Claude Desktop config file:

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

Add (or merge into) the mcpServers block:

{
  "mcpServers": {
    "openstudio-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "./tests/assets:/inputs",
        "-v", "./runs:/runs",
        "-v", "./.claude/skills:/skills:ro",
        "-e", "OPENSTUDIO_MCP_MODE=prod",
        "openstudio-mcp:dev", "openstudio-mcp"
      ]
    }
  }
}
  • ./tests/assets:/inputs — mounts the included test models so you can experiment right away. Replace with your own folder (e.g. ~/my-models:/inputs) when ready.
  • ./runs:/runs — simulation outputs are written here
  • ./.claude/skills:/skills:ro — makes workflow guides available via list_skills() / get_skill() tools
  • Restart Claude Desktop after saving the config file

Step 3: Verify Connection

Open Claude Desktop and look for the hammer icon (MCP tools indicator) in the chat input area. Click it to see the openstudio-mcp tools listed. If the icon doesn't appear, check that Docker is running and the config JSON is valid.

Step 4: Start Chatting

Try these prompts in order of complexity:

Simple: "Create an example model and tell me about it"

Medium: "Create a baseline office with ASHRAE System 3 and show me the HVAC components"

Advanced: "Load my model at /inputs/MyBuilding.osm, apply the 90.1-2019 typical building template, and run a simulation"

The AI reads your prompt, picks the right tools from the 142 available, calls them in sequence, and summarizes the results — no scripting required.

Working with Your Own Files

Place files in the /inputs mount (the host folder mapped to /inputs in the config above) rather than uploading them through the chat interface. This ensures the MCP tools can access them directly.

# Example: analyzing an EnergyPlus error file
# 1. Copy to your inputs folder
cp eplusout.err ./tests/assets/

# 2. Reference by MCP path in your prompt
"Analyze the warnings in /inputs/eplusout.err and create a measure to fix them"

Why not upload? File uploads in Claude Desktop activate an Analysis sandbox that can't communicate with MCP tools. The AI may write scripts to handle the task instead of using the 142 specialized MCP tools available. Placing files in /inputs keeps everything in the MCP workflow.

For simulation outputs (results, SQL, HTML reports), these are already in /runs and accessible to all MCP tools automatically.

Other MCP Hosts

VS Code Copilot, Claude Code, Windsurf, and Gemini CLI also support MCP with similar JSON config. See the MCP documentation for host-specific setup.

Client Compatibility

Client Status Notes
Claude Desktop Full support All 142 tools available
Claude Code Full support ToolSearch auto-defers tools for efficient discovery
VS Code Copilot Compatible MCP support via config
Windsurf Compatible Under 100-tool limit
Gemini CLI Compatible Use includeTools/excludeTools if needed
Cursor Not compatible 40-tool hard cap — use Windsurf or Claude Code instead
OpenAI API Compatible Use defer_loading for best results

Claude Code Skills

When using openstudio-mcp with Claude Code, 12 bundled skills provide workflow automation and domain knowledge:

Skill Type Description
/simulate Workflow One-command simulate + results extraction
/energy-report Workflow Comprehensive multi-category energy report
/qaqc Task Pre-simulation model quality check
/add-hvac Task Guided HVAC system selection
/new-building Workflow Full model creation from scratch
/retrofit Workflow Before/after ECM analysis
/view Task Quick 3D model visualization
/troubleshoot Task Diagnose simulation failures and unexpected results
measure-authoring Knowledge Measure creation, SDK method verification, wiring patterns (auto-loaded)
ashrae-baseline-guide Knowledge ASHRAE 90.1 system selection criteria (auto-loaded)
openstudio-patterns Knowledge Tool dependencies and model relationships (auto-loaded)
tool-workflows Knowledge Multi-tool recipes for common operations (auto-loaded)

Workflow/task skills are invoked with /skill-name. Knowledge skills load automatically when relevant.

Workflow Guides for All MCP Clients

The same workflow guides are also available as MCP tools, so any MCP client (Claude Desktop, Cursor, etc.) can discover them:

  • list_skills() — see available workflows with descriptions
  • get_skill(name) — get step-by-step instructions for a specific workflow

Mount the skills directory when running the container: -v ./.claude/skills:/skills:ro


Skills & Tools (142 total)

Skill Discovery (2 tools)

Tool Description
list_skills List available workflow guides
get_skill Get step-by-step instructions for a workflow

Server Info (2 tools)

Tool Description
get_server_status Server health check
get_versions OpenStudio, EnergyPlus, Ruby versions

Model Creation (5 tools)

Primary tools for creating building energy models. create_new_building is the recommended starting point for most workflows.

Tool Description
create_new_building Create complete building end-to-end (geometry + weather + typical template)
create_bar_building Create bar building geometry from building type, floor area, and aspect ratio
create_typical_building Add constructions, loads, HVAC, SWH to a model with geometry
create_example_osm Create minimal single-zone example (testing/demos)
create_baseline_osm Create 10-zone baseline with ASHRAE system 1-10 (testing/demos)

Model Management (4 tools)

Tool Description
inspect_osm_summary Quick structural summary of OSM file
load_osm_model Load OSM into memory for querying/editing
save_osm_model Save in-memory model to disk
list_files Discover files in /inputs and /runs (OSM, EPW, results)

Building (2 tools)

List building stories via list_model_objects("BuildingStory").

Tool Description
get_building_info Building name, area, volume, orientation
get_model_summary Object counts by category

Spaces (6 tools)

Tool Description
list_spaces List all spaces with area/volume
get_space_details Detailed space info (surfaces, loads, zone)
list_thermal_zones List thermal zones with spaces
get_thermal_zone_details Zone equipment, thermostat, multiplier
create_space Create space with optional story/space type
create_thermal_zone Create thermal zone, assign spaces

Geometry (9 tools)

Tool Description
list_surfaces List surfaces (walls, floors, roofs)
get_surface_details Surface vertices, construction, boundary
list_subsurfaces List windows, doors, skylights
create_surface Create surface with explicit 3D vertices
create_subsurface Create window/door on a parent surface
create_space_from_floor_print Extrude floor polygon into space with all surfaces
match_surfaces Intersect + match shared walls between adjacent spaces
set_window_to_wall_ratio Add centered window by glazing ratio (e.g. 0.4 = 40%)
import_floorspacejs Import custom geometry from FloorSpaceJS JSON file

Constructions (5 tools)

List constructions via list_model_objects("Construction"), construction sets via list_model_objects("DefaultConstructionSet").

Tool Description
list_materials List materials with thermal properties
get_construction_details Construction layers with thermal properties
create_standard_opaque_material Create material with conductivity/density
create_construction Create layered construction from materials
assign_construction_to_surface Assign construction to surface

Schedules (2 tools)

List schedules via list_model_objects("ScheduleRuleset").

Tool Description
get_schedule_details Schedule type, values, rules
create_schedule_ruleset Create constant schedule (Fractional/Temp/OnOff)

HVAC (7 tools)

Tool Description
list_air_loops List air loops with zones served
get_air_loop_details Air loop components, sizing, OA system
add_air_loop Create air loop and connect zones
list_plant_loops List plant loops (heating, cooling, condenser)
get_plant_loop_details Plant loop supply/demand components
list_zone_hvac_equipment List zone-level HVAC equipment
get_zone_hvac_details Zone equipment details

Loads (6 tools)

List loads via list_model_objects("People"), list_model_objects("Lights"), etc. Use get_object_fields for definition details.

Tool Description
get_load_details Get detailed info for any load by name (type dispatcher)
create_people_definition Create people load (by area or count)
create_lights_definition Create lighting load (by area or wattage)
create_electric_equipment Create electric equipment load
create_gas_equipment Create gas equipment load
create_infiltration Create infiltration (by area or ACH)

Space Types (1 tool)

List space types via list_model_objects("SpaceType").

Tool Description
get_space_type_details Space type loads, schedules, standards

Simulation (8 tools)

Tool Description
validate_osw Validate OSW workflow file
run_osw Run EnergyPlus simulation from an OSW file
run_simulation Run simulation from just an OSM + optional EPW
get_run_status Poll simulation run status
get_run_logs Tail simulation logs
get_run_artifacts List simulation output files
cancel_run Cancel running simulation
validate_model Pre-simulation check: weather, design days, HVAC, constructions

Results (12 tools)

Tool Description
extract_summary_metrics Extract EUI, energy, unmet hours from results
read_file Read any file by absolute path (all mounts)
copy_file Copy file to host-mounted path
extract_end_use_breakdown Energy breakdown by end use and fuel type (IP/SI)
extract_envelope_summary Opaque + fenestration U-values and areas
extract_hvac_sizing Autosized zone and system HVAC capacities
extract_zone_summary Per-zone areas, conditions, multipliers
extract_component_sizing Autosized HVAC component values (filterable)
query_timeseries Time-series output variable data with date/cap filters
extract_simulation_errors Parse eplusout.err into Fatal/Severe/Warning lists
list_output_variables List available output variables from completed simulation
compare_runs Compare two runs: EUI delta, per-fuel end-use breakdown

Simulation Outputs (2 tools)

Tool Description
add_output_variable Add EnergyPlus output variable
add_output_meter Add EnergyPlus output meter

HVAC Systems (8 tools)

Tool Description
add_baseline_system Add ASHRAE 90.1 baseline system (types 1-10)
list_baseline_systems List all baseline + modern template types
get_baseline_system_info Get metadata for specific system type
replace_air_terminals Replace ALL terminals on an air loop
replace_zone_terminal Replace terminal on a single zone
add_doas_system Add DOAS with fan coils, radiant, or chilled beams
add_vrf_system Add VRF multi-zone heat pump system
add_radiant_system Add low-temperature radiant heating/cooling

Component Properties (10 tools)

List HVAC components via list_model_objects("BoilerHotWater"), loop detail tools, etc.

Tool Description
get_component_properties Read all properties of a named component
set_component_properties Modify properties on a named component
set_economizer_properties Modify OA economizer settings on air loop
set_sizing_properties Modify plant loop sizing (exit temp, delta-T)
set_sizing_system_properties Set air loop SizingSystem properties (SAT, OA, flow methods)
get_sizing_system_properties Read all SizingSystem properties for air loop
set_sizing_zone_properties Set SizingZone properties (bulk, supports zone lists)
get_sizing_zone_properties Read all SizingZone properties for a zone
get_setpoint_manager_properties Read SPM properties (7 types supported)
set_setpoint_manager_properties Modify SPM properties (7 types supported)

Loop Operations (9 tools)

Tool Description
create_plant_loop Create plant loop with pump, bypass, and SPM
add_supply_equipment Add boiler/chiller/tower to plant loop supply
remove_supply_equipment Remove equipment from plant loop supply
add_demand_component Add coil/heater to plant loop demand side
remove_demand_component Remove component from plant loop demand
add_zone_equipment Add baseboard/unit heater to thermal zone
remove_zone_equipment Remove equipment from thermal zone
remove_all_zone_equipment Batch-remove ALL equipment from multiple zones
set_zone_equipment_priority Reorder zone equipment cooling/heating priority

Object Management (5 tools)

Tool Description
delete_object Delete any named object (28+ supported types)
rename_object Rename any named object
list_model_objects List objects of any type (CamelCase, IDD colon, or underscore formats)
get_object_fields Read all properties of any object via introspection — returns values + available setters
set_object_property Write any property on any object via official setters — auto-coerces value types

Weather & Simulation Config (7 tools)

Tool Description
list_weather_files List available EPW files with companion .stat/.ddy files
get_weather_info Read weather file info (city, lat, lon, timezone)
add_design_day Add heating/cooling design day
get_simulation_control Read sizing flags and timesteps per hour
set_simulation_control Modify sizing flags and/or timestep
get_run_period Read run period begin/end dates
set_run_period Set run period dates (auto-enables weather file run)

Measures (2 tools)

Tool Description
list_measure_arguments List measure arguments with defaults and choices
apply_measure Apply OpenStudio measure to in-memory model

Measure Authoring (4 tools)

Create custom OpenStudio measures with AI-generated code, test them, and apply to models. See Example 1, Example 2, and Example 19 (full E2E retrofit).

Tool Description
list_custom_measures List all custom measures created with create_measure
create_measure Create custom Ruby/Python ModelMeasure with user-provided code
test_measure Run tests for a custom measure (auto-detects language)
edit_measure Edit an existing custom measure's code or arguments

ComStock Measures (1 tool)

~61 bundled ComStock measures (openstudio-standards-based templates for space types, constructions, HVAC, schedules). Pre-installed in Docker image. Creation tools that use these measures are listed in Model Creation above.

Tool Description
list_comstock_measures List bundled measures with category filter (baseline/upgrade/setup)

API Reference (2 tools)

Tool Description
search_api Look up OpenStudio SDK classes and setter/getter methods — verify methods exist before calling
search_wiring_patterns Find Ruby wiring recipes for HVAC components (24 patterns: beams, DOAS, VRF, plant loops, etc.)

Tool Router (1 tool)

Tool Description
recommend_tools Given a task description, recommend the relevant tool group

Common Measures (20 tools)

~79 bundled openstudio-common-measures-gem measures (reporting, thermostats, envelope, renewables, visualization, model cleanup). Pre-installed in Docker image. 20 curated measures with 21 dedicated wrapper tools.

Tool Description
list_common_measures List bundled measures with category filter (reporting/thermostat/envelope/loads/renewables/etc.)
view_model Generate interactive 3D Three.js HTML viewer of model geometry
view_simulation_data Generate 3D viewer with simulation data overlaid on surfaces
generate_results_report Comprehensive HTML report (~25 sections: energy, HVAC, envelope, zones)
run_qaqc_checks ASHRAE baseline QA/QC checks (efficiency, capacity, envelope, loads)
adjust_thermostat_setpoints Shift all heating/cooling setpoints by degree offset
replace_window_constructions Bulk-replace all exterior window constructions
enable_ideal_air_loads Enable ideal air loads on all zones (quick sizing studies)
clean_unused_objects Remove orphan objects and unused resources
change_building_location Set weather file + climate zone + design days
set_thermostat_schedules Apply thermostat schedules from library
replace_thermostat_schedules Replace existing thermostat schedules
shift_schedule_time Shift schedule profiles by hours
add_rooftop_pv Add rooftop PV panels
add_pv_to_shading Add PV to shading surfaces by type
add_ev_load Add electric vehicle charging load
add_zone_ventilation Add zone ventilation design flow rate
set_lifecycle_cost_params Set lifecycle cost analysis parameters
add_cost_per_floor_area Add cost per floor area to building
set_adiabatic_boundaries Set exterior walls/floors to adiabatic

ASHRAE Baseline Systems

All 10 ASHRAE 90.1 Appendix G baseline systems are supported via add_baseline_system:

System Type Description
01 PTAC Packaged terminal AC (zone-level)
02 PTHP Packaged terminal heat pump (zone-level)
03 PSZ-AC Packaged single-zone rooftop AC
04 PSZ-HP Packaged single-zone heat pump
05 Packaged VAV w/ Reheat VAV with hot water reheat coils
06 Packaged VAV w/ PFP Boxes VAV with parallel fan-powered boxes
07 VAV w/ Reheat Central VAV, chiller + boiler + cooling tower
08 VAV w/ PFP Boxes Central VAV with parallel fan-powered terminal
09 Gas Unit Heater Heating-only (warehouses, garages)
10 Electric Unit Heater Heating-only, electric

Plus 3 modern templates: DOAS, VRF, Radiant.


Supported HVAC Component Types

The component properties tools can query and modify these 15 HVAC component types:

Category Components
Coils CoilHeatingGas, CoilHeatingElectric, CoilHeatingWater, CoilCoolingWater, CoilCoolingDXSingleSpeed, CoilCoolingDXTwoSpeed, CoilHeatingDXSingleSpeed
Plant BoilerHotWater, ChillerElectricEIR, CoolingTowerSingleSpeed
Fans FanConstantVolume, FanVariableVolume, FanOnOff
Pumps PumpConstantSpeed, PumpVariableSpeed

Examples

19 worked examples with full tool-call sequences — click to expand:

# Example Description
1 Custom Measure: Lighting Write a measure to reduce lighting, compare before/after EUI
2 Custom Measure: Chilled Beams Write a complex HVAC measure, replace terminals, compare energy
3 Baseline Comparison Compare ASHRAE System 3 vs System 7 EUI
4 HVAC Design Exploration DOAS + fan coils, tune setpoints, resize components
5 Envelope Retrofit Upgrade wall insulation, measure heating impact
6 Internal Loads People, lighting, plug loads with schedules
7 Full Building Model Spaces, zones, HVAC, loads, weather, simulate
8 Geometry from Scratch Floor-print extrusion, surface matching, glazing
9 Fenestration by Orientation Per-orientation window-to-wall ratios
10 Typical Building (ComStock) 90.1-2019 template: constructions, loads, HVAC
11 Results Deep Dive End-use breakdown, envelope, HVAC sizing, timeseries
12 /simulate One-command simulate + results
13 /energy-report Comprehensive multi-category report
14 /qaqc Pre-simulation model quality check
15 /add-hvac Guided ASHRAE system selection
16 /new-building Full model creation from scratch
17 /retrofit Before/after ECM analysis
18 /view Interactive 3D model visualization
19 SystemD Four-Pipe Beam Retrofit End-to-end: load 44-zone model, baseline sim, author measure, retrofit sim, compare

Testing

For the full testing guide — framework details, annotated examples, CI shards, and how to write new tests — see docs/testing/ (or docs/testing/testing.md for the contributor guide).

Quick start

# Unit tests (no Docker)
pytest tests/test_skill_registration.py -v

# Integration tests (Docker)
docker build -t openstudio-mcp:dev -f docker/Dockerfile .

docker run --rm -v "$PWD:/repo" -v "$PWD/runs:/runs" \
  -e RUN_OPENSTUDIO_INTEGRATION=1 -e MCP_SERVER_CMD=openstudio-mcp \
  openstudio-mcp:dev bash -lc 'cd /repo && pytest -vv -s tests/'

Dev vs Prod Mode

Mode Purpose Behavior
dev (default) Local development FastMCP banner + INFO logs
prod MCP host usage Banner disabled, quieter logs
# Prod mode (recommended for MCP hosts)
docker run --rm -i -e OPENSTUDIO_MCP_MODE=prod openstudio-mcp:dev openstudio-mcp

In prod mode, stdout is reserved exclusively for MCP JSON-RPC messages. Logs go to stderr.


Architecture

  • Transport: stdio (container spawned by host)
  • Protocol: MCP (JSON-RPC over stdin/stdout)
  • Model state: single in-memory model via model_manager
  • Runs: stored under /runs/<run_id>/
  • Skills pattern: each skill in mcp_server/skills/<name>/ with tools.py (MCP registration) + operations.py (business logic)

Full system diagram, security analysis & hardening recommendations: docs/architecture.md


Contributing

Adding a new MCP skill

  1. Create mcp_server/skills/<name>/__init__.py, operations.py, tools.py
  2. operations.py — pure business logic, returns {"ok": True/False, ...} dicts
  3. tools.py — exports register(mcp), defines MCP tool schemas
  4. Add tests in tests/test_<name>.py
  5. Add CI step in .github/workflows/ci.yml
  6. The skill auto-registers via skills/__init__.py discovery
  7. Update EXPECTED_TOOLS in tests/test_skill_registration.py
  8. Update tool counts in README.md and CLAUDE.md

Adding a new Claude Code skill (workflow guide)

  1. Create .claude/skills/<name>/SKILL.md with YAML frontmatter:
    ---
    name: my-skill
    description: Short description for discovery
    ---
  2. Add workflow instructions in the markdown body referencing MCP tool names
  3. For user-invocable skills, add user-invocable: true (or omit — default)
  4. For background knowledge, add user-invocable: false
  5. For fire-and-forget workflows, add context: fork
  6. Add integration test in tests/test_skill_<name>.py exercising the tool sequence
  7. Add test to a CI shard in .github/workflows/ci.yml
  8. Add example doc in docs/examples/<N>_<name>.md
  9. Update README examples section and Claude Code Skills table
  10. The skill auto-appears in list_skills() / get_skill() via the /skills mount

Adding a new HVAC component type

  1. Add _get_<type>_props(obj) and _set_<type>_props(obj, properties) in components.py
  2. Add entry to COMPONENT_TYPES dict
  3. Add test in tests/test_component_properties.py
  4. No dynamic dispatch — every OpenStudio API call must be explicit and grepable

License

See LICENSE.

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors

Languages