# OpenStudio MCP Server - User Guide
## What is this?
This server allows AI assistants (like Claude) to work with OpenStudio building energy models. You can ask Claude to analyze, modify, or create building models, and it will use these tools to do the work.
## Quick Start
### 1. Load a Model
Place your `.osm` file in the `sample_files/models/` directory, then ask Claude:
```
"Load the model R2F-Office-Hub-006.osm"
```
Claude will use the `load_osm_model` tool to load it.
### 2. Inspect the Model
Once loaded, you can ask questions like:
```
"How many spaces are in this building?"
"What are the thermal zones?"
"Show me the HVAC systems"
"List all the materials used"
```
Claude will use tools like `list_spaces`, `list_thermal_zones`, `list_air_loops`, and `list_materials`.
### 3. Export to EnergyPlus
To run simulations in EnergyPlus, convert the model:
```
"Convert this model to IDF format"
```
Claude will use the `convert_to_idf` tool.
## Available Tools
### File Operations
- **load_osm_model** - Load an OpenStudio model file
- **save_osm_model** - Save changes to the model
- **convert_to_idf** - Export to EnergyPlus IDF format
- **copy_file** - Copy files between locations
### Building Information
- **get_model_summary** - Overall model statistics
- **get_building_info** - Building object details
- **list_spaces** - All spaces in the building
- **get_space_details** - Specific space information
- **list_thermal_zones** - All thermal zones
- **get_thermal_zone_details** - Specific zone information
### Systems & Loads
- **list_air_loops** - HVAC air systems
- **list_people_loads** - Occupancy definitions
- **list_lighting_loads** - Lighting power densities
- **list_electric_equipment** - Equipment loads
### Materials
- **list_materials** - All construction materials
- **list_schedule_rulesets** - Operating schedules
### Server Status
- **get_server_info** - Server configuration
- **get_current_model_status** - Currently loaded model
## How It Works
1. **You ask Claude** to do something with a building model
2. **Claude selects appropriate tools** based on your request
3. **The MCP server executes the tools** using the OpenStudio library
4. **Results are returned** as JSON data
5. **Claude interprets and presents** the results in natural language
## File Locations
- **Your models**: Place in `sample_files/models/`
- **Weather files**: Place in `sample_files/weather/`
- **Output files**: Generated in `outputs/`
- **Logs**: Server logs in `logs/`
## Example Conversations
### Example 1: Basic Analysis
**You**: "Load R2F-Office-Hub-006.osm and tell me about it"
**Claude**: Uses these tools in sequence:
1. `load_osm_model("R2F-Office-Hub-006.osm")`
2. `get_model_summary()`
3. `list_spaces()`
4. `list_thermal_zones()`
Then tells you: "This building has 12 spaces organized into 4 thermal zones..."
### Example 2: HVAC Analysis
**You**: "What HVAC systems are in this building?"
**Claude**: Uses:
1. `list_air_loops()`
Then explains the system configuration.
### Example 3: Export for Simulation
**You**: "Prepare this model for EnergyPlus simulation"
**Claude**: Uses:
1. `convert_to_idf()`
Then confirms the IDF file location.
## Troubleshooting
### "Model not loaded" error
- Make sure you loaded a model first with `load_osm_model`
- Claude should automatically load the model if you mention it
### "File not found" error
- Check that your `.osm` file is in `sample_files/models/`
- File names are case-sensitive
### Claude doesn't use the tools
- Try being more specific: "Use the OpenStudio tools to..."
- Restart Claude Desktop if the server connection is lost
## Tips for Better Results
1. **Be specific** about file names when you have multiple models
2. **Load the model first** before asking questions about it
3. **Ask one thing at a time** for clearer responses
4. **Check the outputs folder** for generated files
5. **Restart Claude** if tools stop working
## Need Help?
- Check server logs in `logs/openstudio_mcp_server.log`
- Verify the Docker container is running
- Make sure the `.osm` file is valid OpenStudio format
- Try restarting Claude Desktop
---
**Ready to start!** Place your model in `sample_files/models/` and ask Claude to analyze it.