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
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.
- 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.
git clone https://github.com/NatLabRockies/openstudio-mcp.git
cd openstudio-mcp
docker build -t openstudio-mcp:dev -f docker/Dockerfile .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 vialist_skills()/get_skill()tools- Restart Claude Desktop after saving the config file
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.
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.
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.
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 | 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 |
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.
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 descriptionsget_skill(name)— get step-by-step instructions for a specific workflow
Mount the skills directory when running the container: -v ./.claude/skills:/skills:ro
| Tool | Description |
|---|---|
list_skills |
List available workflow guides |
get_skill |
Get step-by-step instructions for a workflow |
| Tool | Description |
|---|---|
get_server_status |
Server health check |
get_versions |
OpenStudio, EnergyPlus, Ruby versions |
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) |
| 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) |
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 |
| 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 |
| 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 |
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 |
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) |
| 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 |
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) |
List space types via list_model_objects("SpaceType").
| Tool | Description |
|---|---|
get_space_type_details |
Space type loads, schedules, standards |
| 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 |
| 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 |
| Tool | Description |
|---|---|
add_output_variable |
Add EnergyPlus output variable |
add_output_meter |
Add EnergyPlus output meter |
| 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 |
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) |
| 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 |
| 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 |
| 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) |
| Tool | Description |
|---|---|
list_measure_arguments |
List measure arguments with defaults and choices |
apply_measure |
Apply OpenStudio measure to in-memory model |
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 |
~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) |
| 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 | Description |
|---|---|
recommend_tools |
Given a task description, recommend the relevant tool group |
~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 |
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.
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 |
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 |
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).
# 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/'| 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-mcpIn prod mode, stdout is reserved exclusively for MCP JSON-RPC messages. Logs go to stderr.
- 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>/withtools.py(MCP registration) +operations.py(business logic)
Full system diagram, security analysis & hardening recommendations: docs/architecture.md
- Create
mcp_server/skills/<name>/__init__.py,operations.py,tools.py operations.py— pure business logic, returns{"ok": True/False, ...}dictstools.py— exportsregister(mcp), defines MCP tool schemas- Add tests in
tests/test_<name>.py - Add CI step in
.github/workflows/ci.yml - The skill auto-registers via
skills/__init__.pydiscovery - Update
EXPECTED_TOOLSintests/test_skill_registration.py - Update tool counts in
README.mdandCLAUDE.md
- Create
.claude/skills/<name>/SKILL.mdwith YAML frontmatter:--- name: my-skill description: Short description for discovery ---
- Add workflow instructions in the markdown body referencing MCP tool names
- For user-invocable skills, add
user-invocable: true(or omit — default) - For background knowledge, add
user-invocable: false - For fire-and-forget workflows, add
context: fork - Add integration test in
tests/test_skill_<name>.pyexercising the tool sequence - Add test to a CI shard in
.github/workflows/ci.yml - Add example doc in
docs/examples/<N>_<name>.md - Update README examples section and Claude Code Skills table
- The skill auto-appears in
list_skills()/get_skill()via the/skillsmount
- Add
_get_<type>_props(obj)and_set_<type>_props(obj, properties)incomponents.py - Add entry to
COMPONENT_TYPESdict - Add test in
tests/test_component_properties.py - No dynamic dispatch — every OpenStudio API call must be explicit and grepable
See LICENSE.