openstudio

The OpenStudio MCP Server provides a suite of tools to load, inspect, and manipulate OpenStudio Model (OSM) files via natural language. Built atop the OpenStudio-Toolkit, it exposes capabilities for loading and saving models, exporting to IDF, inspecting buildings, spaces, and HVAC elements, and generating interactive visualizations. When connected through Claude Desktop or another MCP client, you can invoke specific tools like load_osm_model, get_model_summary, apply_view_model, and list_spaces to accomplish modeling tasks without manual scripting. The server supports intelligent file discovery, fuzzy matching for file names, and dual-environment operation (Docker and Claude Desktop). To get started, ensure the server is running in Docker and that Claude Desktop is configured to point at the mapped workspace where your repository lives.

Prerequisites:

• Docker Desktop installed and running
• Access to your OpenStudio MCP Server repository
• Claude Desktop or another MCP client (optional, for integration)

Quick Start (Docker - recommended):

1. Clone the repository

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

2. Build the Docker image (from the repository root):

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

3. Run the MCP server inside Docker (example command you can adapt):

# Ensure you replace the host paths with actual locations on your machine
docker 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

4. Configure Claude Desktop (if using Claude) to point to the server similarly to the example in the README, ensuring proper volume mounts and the working directory match your setup.
5. Verify installation by asking Claude Desktop: "What OpenStudio tools are available?"

Tips and considerations:

• The outputs directory is created inside the repository's outputs/ (mapped to your host via the workspace volume).
• For Windows hosts, follow the two-volume-mount guidance carefully: one mount provides host C: drive access, the other mounts the server source code for the container to run.
• If you modify the server code, rebuild the Docker image to pick up changes.
• Ensure the OpenStudio SDK and Python bindings used by the container are compatible with your models.
• Use the Intelligent File Discovery and fuzzy matching features to locate OSM files across different folders and Claude Desktop uploads.