OpenStudio

You run an MCP server that lets AI assistants interact with OpenStudio models. Load, inspect, and manipulate OpenStudio Model (OSM) files through a rich set of tools, all accessible via natural language. This makes model analysis, conversion, and reporting fast and repeatable, whether you’re prototyping, teaching, or validating energy models.

How to use

You interact with the server through an MCP client. Start by loading an OpenStudio model file, then ask questions or give commands in natural language to explore geometry, HVAC systems, schedules, and material properties. Common workflows include loading a model, listing spaces and thermal zones, applying templates, visualizing the model, exporting to IDF, and saving updated models.

How to install

Prerequisites you need before starting are Docker Desktop and a compatible environment for your AI assistant integration (Claude Desktop, VS Code, or Cursor). You will run the MCP server inside a Docker container and connect your MCP client to it.

Step 1: Prepare your environment

• Install Docker Desktop on your machine.
• Install Claude Desktop or another MCP client as your integration layer.
• Ensure you have a working internet connection for initial setup.

Step 2: Clone the server repository

cd openstudio-mcp-server```

Step 3: Build the Docker image for development
```docker build -t openstudio-mcp-dev -f .devcontainer/Dockerfile .devcontainer```

Step 4: Create the MCP client configuration for Claude Desktop (Windows example)

{
  "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"
      ]
    }
  }
}

• Replace C:\PATH\TO\YOUR\openstudio-mcp-server with the actual path where you cloned the repository.
• This config mounts your host C drive to the container for file access and mounts the server source so the container can run the MCP server scripts.

Step 5: Start Claude Desktop or your MCP client and verify connectivity
- Restart Claude Desktop to load the MCP server configuration.
- In your client, request the available tools or try a simple load operation to confirm the server responds.

Step 6: Verify installation
- In your MCP client, ask for available OpenStudio tools. The client should list the tools exposed by the server once connected.

## Additional sections

File access and container setup are critical. The server runs in Docker with two necessary volume mounts to ensure you can load models from your host filesystem and save outputs back to your machine. The first mount exposes your C: drive to the container, allowing file reads and writes, while the second mount keeps the server source code accessible so changes on the host reflect inside the container.

Key practices to avoid common issues:
- Use absolute host paths when referring to files from the MCP client.
- Place your model files in a known location inside the host-mounted workspace to ensure the server can discover them.
- When you modify server code locally, the container reflects those changes through the mounted workspace.

If you encounter issues during startup or tool usage, review container logs and ensure Docker Desktop is running without permission or path errors. Restart the MCP client and verify the server status if necessary.

## Troubleshooting

Model not loaded: Load a model first with load\_osm\_model and confirm the file exists in the mounted workspace.
File not found: Verify the path is correct and that the file resides in the mounted workspace directory.
Tools not appearing: Check the MCP server connection status in your client UI and inspect server logs located under logs in the workspace if available.
Docker issues: Ensure Docker Desktop is running and the volume mount path is absolute. Confirm the container image built successfully.

## Available tools

### load\_osm\_model

Load an OpenStudio Model (OSM) file into the MCP server, resolving intelligent paths and preparing it for analysis.

### save\_osm\_model

Save the currently loaded OSM model after modifications.

### convert\_to\_idf

Export the loaded OSM model to EnergyPlus IDF format for simulation.

### copy\_file

Copy files with fuzzy matching and smart discovery to quickly locate relevant inputs or outputs.

### get\_model\_summary

Generate a comprehensive summary of the loaded model, including statistics and key attributes.

### get\_building\_info

Retrieve detailed information about building objects within the model.

### apply\_view\_model

Create an interactive HTML visualization of geometry, HVAC systems, zones, and materials.

### apply\_space\_type\_and\_construction\_set\_wizard

Apply ASHRAE 90.1 templates to spaces and construction sets for standardization.

### list\_spaces

List all spaces with their properties to understand the building layout.

### get\_space\_details

Provide detailed information about a specific space, including connections and properties.

### list\_thermal\_zones

List all thermal zones defined in the model.

### get\_thermal\_zone\_details

Get detailed information about a particular thermal zone.

### list\_materials

List all materials with their thermal properties used in constructions.

### list\_air\_loops

List all air loop HVAC systems present in the model.

### list\_people\_loads

List occupancy-related internal loads.

### list\_lighting\_loads

List lighting power densities and related lighting information.

### list\_electric\_equipment

List electrical equipment loads within the model.

### list\_schedule\_rulesets

List all schedule rulesets defined in the model.

### get\_server\_info

Retrieve server configuration and current status.

### get\_current\_model\_status

Check which model is currently loaded and its readiness for queries.