OpenStudio MCP
openstudio-mcp
MCP server for building energy modeling: an agent builds an OpenStudio model, runs EnergyPlus and reads the results.
- 57 ★ on the repository
- Last commit
Extended access
Why this level
- The agent writes and runs Ruby and Python measures and creates files in mounted folders.
- Measure code runs in a sandbox, but on macOS and Windows without Docker only environment filtering applies.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/openstudio-mcpDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent writes and runs Ruby and Python measures and creates files in mounted folders.
- Measure code runs in a sandbox, but on macOS and Windows without Docker only environment filtering applies.
This is third-party code. Review the repository files before installing.
What it does
The server wraps OpenStudio and EnergyPlus in more than 150 MCP tools. An agent creates a building from floor plans, sets up heating and ventilation systems, changes insulation and glazing, runs an annual simulation and reads the results: energy use intensity, unmet heating hours and HTML reports. The model can be edited with ready-made measures. The agent writes a measure in Ruby or Python, tests it, applies it and compares figures before and after. The server runs in a Docker container and measure code runs in a separate sandbox. A shared server mode offers HTTP with isolated sessions and tokens.
Who it is for. Energy modelers and HVAC engineers who simulate building energy use in OpenStudio and want less manual model assembly.
Good fit when
- A ten-zone office has to be built with a VAV system and run for a year right away.
- Two HVAC options, such as VAV and VRF heat pumps, are compared by energy use.
- A gbXML model is imported and checked before simulation.
- A measure from the local folder is applied to a model and its effect appears in a figures summary.
Not a fit when
- The calculation has to run in other software: the server works only with OpenStudio and EnergyPlus.
- Docker is not installed on the machine and cannot be.
- Measures come from untrusted sources without isolation: on macOS and Windows without Docker there is no sandbox.
Example request
Create a ten-zone office with a VAV reheat system, run an annual simulation and show the energy use intensity.MCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
OPENSTUDIO_MCP_MODE- Run mode, set to `prod` in the README example.
MCP_TRANSPORT- The value `http` switches on a shared multi-user server instead of stdio.
OSMCP_SANDBOX- Isolation level for measure code: `auto` by default, `off` disables it.
Limitations
The quick start needs Docker Desktop running. The agent sees only files in mounted folders: models go in `/inputs`, results are written to `/runs` and measures to `/measures`. OpenStudio measures are Ruby or Python, and their code is treated as untrusted. The Landlock and seccomp sandbox works on Linux and inside the Docker Desktop VM. The source is licensed under LICENSE.txt and GitHub did not detect the license type.
How to disable. Remove the `openstudio-mcp` entry from the client config. The image is removed with `docker rmi nrel/openstudio-mcp:v1.2.1`, and simulation results stay in the `/runs` folder on the host.
FAQ
How do I connect OpenStudio MCP to Claude Code?
Pull the image with `docker pull nrel/openstudio-mcp:v1.2.1` and add a `docker run --rm -i` launch to `.mcp.json` with three mounts and `OPENSTUDIO_MCP_MODE=prod`. The README lists Claude Code as a fully supported client.
Why does the agent not open an attached model file?
An attachment reaches the chat but not the container's disk. Put the file in the folder mounted as `/inputs` and refer to `/inputs/file-name` in the prompt.
Where do simulation results go?
To the folder mounted as `/runs`, under `/runs/<run_id>/`: the OSM model, the SQL database and HTML reports. Without the mount, results vanish when the container exits.
Is it safe to run third-party measures?
Measure code is treated as untrusted. By default it runs as an unprivileged user, without network access and with a restricted file system. `OSMCP_SANDBOX=off` disables protection and suits only your own code.
Can the agent be stopped from writing code?
Yes. `OSMCP_ENABLE_CODE_TOOLS=false` removes `create_measure`, `edit_measure`, `create_python_plugin`, `edit_python_plugin` and `install_plugin_packages`.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server with 35 tools for EnergyPlus building energy models: loading IDF files, editing parameters, simulation and plots.
Official MCP server from the OpenSearch project exposes a cluster to agents: indexes, mappings, DSL search and shard state.
An MCP server that lets an agent run local Stata: regressions, econometrics, replicating computations from papers
An MCP server with a toolbox for global briefs: markets, SEC filings, conflict, climate and news from open sources
The official MathWorks MCP server: the agent starts and quits MATLAB, writes and runs code, and checks it for errors and style
Official Data Commons MCP server: an agent finds statistical indicators and pulls observations for countries, regions and cities.
README in short
The quick start runs through Docker for Claude Desktop and Codex, an HTTP mode for teams, a sandbox for measure code and references for HVAC systems. The project is published in SoftwareX and the repository has more than 500 integration tests.