openstudio-mcp-server: Instructions file for Claude Code

Claude AI Developer Guide - OpenStudio MCP Server

Purpose: Guide AI assistants working with this Docker-based MCP server for OpenStudio building energy modeling.

Critical Context: This server runs inside Docker to manage complex system-level OpenStudio dependencies (Python bindings, Ruby libraries, X11 libraries).

---

Commands Reference

Docker Build

Build the Docker image after changing dependencies or Dockerfile:

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

When to rebuild:

• After modifying pyproject.toml dependencies
• After changing .devcontainer/Dockerfile
• After updating OpenStudio version

Docker Run (Production)

Run the server in Docker as configured in Claude Desktop:

docker run --rm -i \
  -v C:\:/mnt/c \
  -v C:\openstudio-mcp-server:/workspace \
  -w /workspace/openstudio-mcp-server \
  openstudio-mcp-dev \
  uv run openstudio_mcp_server/server.py

Volume Mounts:

• -v C:\:/mnt/c - Entire C: drive access (enables smart path translation)
• -v C:\openstudio-mcp-server:/workspace - Server source code

Local Debug (Inside Container)

For testing without Claude Desktop connection:

uv run openstudio_mcp_server/server.py

Requirements:

• Must run inside the Docker container (or with OpenStudio installed locally)
• Container must have access to OpenStudio Python bindings via PYTHONPATH

---

Architecture & Components

Overview

┌─────────────────────────────────────────────────────┐
│ Claude Desktop (Client)                             │
└────────────────┬────────────────────────────────────┘
                 │ MCP Protocol (stdio)
                 ↓
┌─────────────────────────────────────────────────────┐
│ Docker Container (openstudio-mcp-dev)               │
│                                                     │
│  ┌──────────────────────────────────────────────┐  │
│  │ server.py (FastMCP Entry Point)              │  │
│  │  - Defines MCP tools                         │  │
│  │  - Handles client communication              │  │
│  │  - Routes requests to OpenStudioManager      │  │
│  └─────────────────┬────────────────────────────┘  │
│                    │                                │
│  ┌─────────────────▼────────────────────────────┐  │
│  │ openstudio_tools.py (Controller Layer)       │  │
│  │  - OpenStudioManager class                   │  │
│  │  - Minimal logic (validation, path resolution) │
│  │  - Calls openstudio_toolkit functions        │  │
│  │  - Formats responses as JSON                 │  │
│  └─────────────────┬────────────────────────────┘  │
│                    │                                │
│  ┌─────────────────▼────────────────────────────┐  │
│  │ openstudio_toolkit/ (Business Logic)         │  │
│  │  - Robust OpenStudio operations              │  │
│  │  - Direct interaction with OpenStudio API    │  │
│  │  - Pure functions (no state)                 │  │
│  │  - osm_objects/, tasks/, utils/              │  │
│  └──────────────────────────────────────────────┘  │
│                                                     │
│  System Dependencies:                               │
│  - OpenStudio 3.7.0 (installed in /usr/local/)     │
│  - Python 3.12                                      │
│  - X11 libraries (for OpenStudio rendering)        │
└─────────────────────────────────────────────────────┘