idfkit-mcp
OfficialSummary: idfkit-mcp is an MCP server that lets AI assistants author, validate, simulate, and analyze EnergyPlus building energy models end to end.
Create and edit models — start a new model (
new_model), load IDF/epJSON/OSM files (load_model,convert_osm_to_idf), then add, update, duplicate, rename, or remove objects (single or bulk).Inspect models — list/search objects, list object types, and get typed zone summaries (floor area, volume, surfaces, constructions, schedules, HVAC).
Explore the schema — browse object types by group, search schema, describe field definitions with constraints/defaults/references, and list valid names for reference fields.
Validate models — run schema validation (
validate_model) and domain-level integrity checks (check_model_integrity) before simulating.Run simulations — execute EnergyPlus (annual or design-day) and migrate models forward across EnergyPlus versions (
migrate_model).Analyze results — list/query output variables, query time-series and tabular reports, export time series to CSV, analyze peak heating/cooling loads, and browse interactive report viewers.
Find weather data — search weather stations and download EPW/DDY files.
Visualize — interactive 3D geometry viewer and schedule heatmap viewer (MCP Apps).
Search documentation — full-text search across EnergyPlus docs and read full doc sections with links.
Manage files and sessions — upload/list files via
file_manager, save models to disk, review the change log, and reset sessions withclear_session.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@idfkit-mcp create a single-zone office with a packaged rooftop unit"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
idfkit-mcp
An MCP server that lets an AI assistant author, validate and simulate EnergyPlus models with idfkit.
idfkit · Developers · EnergyPlus docs · Envelop · MCP · Shoebox · GitHub
An MCP server that lets AI assistants work directly with EnergyPlus building energy models. Connect it to Claude, ChatGPT, Cursor, Codex, or any MCP-compatible client and use natural language to:
Build models from scratch — describe a building and let the agent create zones, surfaces, constructions, schedules, and HVAC systems
Edit existing models — load an IDF or epJSON file, rename objects, swap materials, adjust setpoints, and validate as you go
Run simulations — pick a weather file, launch EnergyPlus, and query or export the results without leaving the conversation
Explore the schema — ask what fields a
ZoneHVAC:IdealLoadsAirSystemaccepts, what values are valid, and get links to the official EnergyPlus documentationSearch the docs — full-text search across the EnergyPlus I/O Reference, Engineering Reference, and other documentation sets hosted on docs.idfkit.com
Built on idfkit, it supports EnergyPlus 8.9 through 26.2 (18 versions with bundled schemas). Schema exploration, model editing, and validation work out of the box with no external dependencies. Running simulations requires a local EnergyPlus install — the server discovers it automatically via PATH, the ENERGYPLUS_DIR env var, or standard OS install locations. The repository's Dockerfile builds a container image locally, with or without EnergyPlus bundled (see Commands); no prebuilt image is published.
Tools
The server exposes 39 tools across eleven categories, plus 10 MCP resources and 4 resource templates for read-only data access:
Category | Tools | What they do |
Schema | 4 | Explore object types, fields, constraints, and valid references |
Model Read | 6 | Load IDF/epJSON/OSM files, inspect objects, search, and read change history |
Model Write | 10 | Create models, add/update/remove/rename/duplicate objects, save, and manage sessions |
Validation | 2 | Schema validation and pre-simulation integrity checks |
Simulation | 8 | Run EnergyPlus, query variables and tabular reports, export time series, analyze peak loads, and view reports |
Weather | 2 | Search weather stations worldwide and download EPW/DDY files |
Geometry | 1 | Interactive 3D building geometry viewer (MCP Apps) |
Schedules | 1 | Interactive schedule heatmap viewer (MCP Apps) |
Migration | 1 | Migrate IDF models forward across EnergyPlus versions |
Documentation | 2 | Search and read EnergyPlus documentation from docs.idfkit.com |
Uploads | 2 |
|
Most tools return structured Pydantic models with an output schema. The exceptions are add_object, update_object and duplicate_object, which return plain dictionaries, and the MCP Apps tools view_geometry, view_schedules and file_manager, which return UI results. Schema, validation, and search results include direct doc_url links to the relevant EnergyPlus documentation.
With the stdio transport, session state (loaded model, simulation results, weather file) is persisted to disk automatically, so clients that restart the server between turns (e.g. Codex) can resume where they left off. HTTP sessions keyed only by the Mcp-Session-Id header are not persisted, because that identifier changes on reconnect; persistence applies over HTTP only to sessions bound to an authenticated principal or an OpenAI session identifier.
Related MCP server: ladybug-tools-mcp
Installation
pip install idfkit-mcpOr with uv:
uv add idfkit-mcpUsage
Run as stdio MCP server (default):
idfkit-mcpRun as Streamable HTTP MCP server:
idfkit-mcp --transport streamable-http --host 127.0.0.1 --port 8000Run with the legacy SSE transport:
idfkit-mcp --transport sse --host 127.0.0.1 --port 8000--transport accepts stdio, sse, http and streamable-http (an alias of http). --host and --port apply to the HTTP and SSE transports only. Print the server version and the idfkit version it runs against:
idfkit-mcp --versionThe server reads these environment variables:
Variable | Default | Effect |
|
| Default for |
|
| Default for |
|
| Default for |
|
| Log level for the server and idfkit |
| unset (in memory) | Directory for disk-backed uploads |
IDFKIT_MCP_OUTPUT_DIRS (allowed directories for files written by save_model and export_timeseries) and IDFKIT_MCP_SIMULATION_DIR (parent directory for simulation runs) are described in the documentation.
Quick MCP Setup
Add idfkit-mcp to your MCP client. Example for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"idfkit": {
"command": "uvx",
"args": ["--from", "idfkit-mcp", "idfkit-mcp"]
}
}
}See MCP Client Setup for all supported clients (Claude Desktop, Cursor, VS Code, Claude Code, Windsurf, ChatGPT, Codex, JetBrains, Cline, Continue, and Zed).
Development
This project uses uv for dependency management and Zensical for documentation.
Setup
# Clone the repository
git clone https://github.com/idfkit/idfkit-mcp.git
cd idfkit-mcp
# Install dependencies and pre-commit hooks
make installCommands
make install # Install dependencies and pre-commit hooks
make check # Run linting, formatting, and type checks
make test # Run tests with coverage
make docs # Serve documentation locally
make docs-test # Test documentation build
make docker-build # Build base Docker image (no EnergyPlus)
make docker-build-sim ENERGYPLUS_TARBALL_URL=<linux-tarball-url> # Build simulation image
make docker-build-sim DOCKER_PLATFORM=linux/amd64 ENERGYPLUS_TARBALL_URL=<linux-x86_64-tarball-url> # Apple Silicon + x86 tarball
make docker-run # Run the base image idfkit-mcp:latest over HTTP, mapping host port 8000 to container port 8000
make docker-run-sim # Run the simulation image idfkit-mcp:sim the same wayReleasing
Create a new release on GitHub with a v-prefixed tag (e.g., v0.11.1).
The release-main workflow (.github/workflows/on-release-main.yml) writes the tag into the version field of pyproject.toml before building, then publishes to PyPI.
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
Available Tools
39 toolsadd_objectA
Add one object. Use batch_add_objects for multiple.
Inputs: object_type (required), name, fields.
analyze_peak_loadsARead-onlyIdempotent
Analyze peak heating and cooling loads for QA/QC.
Decomposes facility and zone-level peaks into components (solar, people, lighting, equipment, infiltration, envelope) and flags potential issues such as unusual peak timing, excessive loads, or component dominance.
Requires a completed simulation with SQL output and the SensibleHeatGainSummary and HVACSizingSummary reports. The decomposition needs a weather-file run period; after a design-day-only run, cooling and heating report available=false and only the sizing loads are populated.
Inputs: no named parameters. Returns: Complete peak load QA/QC analysis.
batch_add_objectsA
Add multiple objects in one call. Continues on errors.
Inputs: objects (required). Returns: Response from ``batch_add_objects``.
check_model_integrityARead-onlyIdempotent
Domain-level pre-simulation QA — catches issues schema validation cannot.
Runs six checks against the loaded model:
Zones with no BuildingSurface:Detailed surfaces
Missing required simulation control objects (Version, Building, Timestep, RunPeriod, SimulationControl)
Orphan schedules (defined but not referenced by any object)
Surface boundary condition mismatches (non-reciprocal 'Surface' pairs)
Fenestration surfaces referencing non-existent host surfaces
ZoneHVAC:EquipmentConnections referencing non-existent zones
Use this after validate_model and before run_simulation. A model can pass validate_model but still fail these checks.
Preconditions: model loaded. Side effects: none — read-only.
Inputs: no named parameters. Returns: Response from ``check_model_integrity``.
clear_sessionADestructive
Reset model and simulation state so you can start fresh.
Unloads the current model, schema, simulation results, migration report, and weather file. Uploaded files are kept so the user can re-load them without re-uploading.
WARNING: Only call this when the user explicitly asks to start over. Do NOT call this to recover from tool errors — those errors are recoverable by retrying the failed tool or calling load_model again.
Inputs: no named parameters. Returns: Response from ``clear_session``.
convert_osm_to_idfCIdempotent
Convert an OSM model to IDF and load it.
Inputs: osm_path (required), output_path (required), overwrite, allow_newer_versions. Returns: Response from ``convert_osm_to_idf``.
describe_object_typeARead-onlyIdempotent
Field schema with types, constraints, defaults, and references. Call before adding objects.
Inputs: object_type (required), version. Returns: Response from ``describe_object_type``.
download_weather_fileAIdempotent
Download EPW/DDY files for a station. Auto-used by run_simulation.
Inputs: wmo, query, state, country. Returns: Response from ``download_weather_file``.
duplicate_objectB
Copy an object with a new name.
Inputs: name (required), new_name (required), object_type (required).
export_timeseriesCIdempotent
Export time series to CSV.
Inputs: variable_name (required), frequency, key_value, environment, +1 more. Returns: Response from ``export_timeseries``.
file_managerB
Upload and manage files. Drop files here to send them to the server.
Inputs: no named parameters.
get_available_referencesARead-onlyIdempotent
List valid names for a reference field (e.g. zone_name).
Inputs: field_name (required), object_type (required). Returns: Response from ``get_available_references``.
get_change_logARead-onlyIdempotent
Return recent model mutation history for this session.
Records add, update, remove, rename, duplicate, load, and new-model operations in chronological order. Useful for auditing what the agent has changed and verifying that edits were applied as intended.
The log is in-memory only and resets when clear_session is called.
Inputs: limit. Returns: Response from ``get_change_log``.
get_doc_sectionARead-onlyIdempotent
Read full content of a doc section from search_docs results.
Inputs: location (required), version, max_length. Returns: Response from ``get_doc_section``.
get_zone_propertiesARead-onlyIdempotent
Typed summary of zone geometry, surfaces, constructions, schedules, and HVAC.
Returns floor area, volume, ceiling height, surface counts by type (walls/floors/roofs/ windows/doors), unique construction names, schedule names referenced by zone loads, HVAC equipment connection names, and thermostat control object names.
Geometry values (area, volume, height) are calculated from BuildingSurface:Detailed vertices and returned as None when no surfaces exist for the zone.
Preconditions: model loaded. Side effects: none — read-only.
Inputs: zone_name. Returns: Response from ``get_zone_properties``.
list_filesA
List all uploaded files with metadata.
Inputs: no named parameters. Returns: result
list_objectsARead-onlyIdempotent
List objects of a type.
By default each object is returned in brief form: name plus schema-required fields
only. Optional fields (economizer settings, enum overrides, etc.) are omitted — set
include_all_fields=True to get every field, or read the
idfkit://model/objects/{type}/{name} resource for one object's full field values.
Inputs: object_type (required), limit, include_all_fields. Returns: Response from ``list_objects``.
list_object_typesARead-onlyIdempotent
Browse object types grouped by category. Filter by group to list individual types.
Inputs: group, limit, version. Returns: Response from ``list_object_types``.
list_output_variablesARead-onlyIdempotent
List output variables and meters from last simulation.
Inputs: limit, search. Returns: Response from ``list_output_variables``.
list_simulation_reportsARead-onlyIdempotent
List all tabular report names available in the last simulation's SQL output.
Use the returned names with query_simulation_table to retrieve specific tables.
Preconditions: simulation completed with SQL output available. Side effects: none — read-only.
Inputs: no named parameters. Returns: result
load_modelAIdempotent
Open an IDF or epJSON file as the active model.
Provide exactly one source: file_path for files on the server's disk, or
upload_name to load a file the user dropped into the file_manager UI.
Inputs: version, file_path, upload_name. Returns: Response from ``get_model_summary`` and ``load_model``.
migrate_modelADestructive
Forward-migrate the loaded model to a newer EnergyPlus version.
Drives the EnergyPlus IDFVersionUpdater transition binaries through the
required chain of steps and replaces the session document with the migrated
one. state.file_path is unchanged — call save_model(path=...) to
persist the migrated model.
Preconditions: model loaded; target version >= current model version. Side effects: replaces the in-memory document; records a change-log entry. Next step: validate_model + check_model_integrity, then save_model.
Read idfkit://migration/report for per-step stdout/stderr and the
structural diff after the call.
Inputs: keep_work_dir, energyplus_dir, target_version. Returns: Response from ``migrate_model``.
new_modelB
Create an empty model.
Inputs: version. Returns: Response from ``new_model``.
query_simulation_tableARead-onlyIdempotent
Query tabular report data from the last simulation's SQL output.
Use this for deeper analysis beyond the structured diagnostics in
idfkit://simulation/results. Tabular data covers every EnergyPlus
summary report: energy use, envelope, HVAC sizing, comfort, and more.
Omit table_name to retrieve all tables within a report at once.
To discover available report names call list_simulation_reports first.
Common report names:
AnnualBuildingUtilityPerformanceSummary— site/source energy, end uses, EUISystemSummary— unmet hours, HVAC sizingEnvelopeSummary— U-values, areas, orientationsEquipmentSummary— HVAC component sizingZoneComponentLoadSummary— peak heating/cooling loads by zoneLightingSummary— lighting power density
Preconditions: simulation completed with SQL output available (sql_available: true
in idfkit://simulation/results).
Side effects: none — read-only.
Inputs: report_name (required), row_name, table_name, column_name. Returns: Response from ``query_simulation_table``.
query_timeseriesBRead-onlyIdempotent
Query time series data from simulation SQL output.
Inputs: variable_name (required), limit, frequency, key_value, +1 more. Returns: Response from ``query_timeseries``.
remove_objectADestructive
Delete an object. Blocked if referenced unless force=True.
Inputs: name (required), object_type (required), force. Returns: Response from ``remove_object``.
remove_objectsADestructive
Delete every object of the given type. No-op when none exist.
Intended for types where individual entries have no canonical addressable
identity (Output:Variable, Output:Meter, …): those parse with
_name="" to support duplicates, so remove_object cannot reach them
individually. Use this when the calling tool owns the entire collection
and wants replace-all semantics (e.g. an output-picker UI).
Blocked when any entry is referenced by other objects unless force=True.
Inputs: object_type (required), force. Returns: Response from ``remove_objects``.
rename_objectA
Rename and auto-update all references.
Inputs: new_name (required), old_name (required), object_type (required). Returns: Response from ``rename_object``.
run_simulationAIdempotent
Execute EnergyPlus on the loaded model — the authoritative runtime validation gate.
Fatal or severe errors mean the model did not simulate correctly. A clean exit does
not guarantee physically reasonable results. After this call, read the resource
idfkit://simulation/results for full QA diagnostics: unmet hours by zone,
end-use energy breakdown, classified warnings, and QA flags that drive the fix loop.
Preconditions: model loaded; weather file set via download_weather_file, or a design-day-only run (design_day=True, annual=False), which needs no weather file. Side effects: writes outputs to output_directory; updates session simulation result. Next step: read idfkit://simulation/results to assess result quality.
Inputs: annual, readvars, design_day, weather_file, +3 more. Returns: Response from ``run_simulation``.
save_modelAIdempotent
Write model to disk as IDF or epJSON.
When file_path is omitted the model is re-saved to its original load
path. An explicit file_path must resolve within an allowed output
directory (IDFKIT_MCP_OUTPUT_DIRS, defaults to CWD) and will not
overwrite an existing file unless overwrite is True.
Inputs: file_path, overwrite, output_format. Returns: Response from ``save_model``.
search_docsBRead-onlyIdempotent
Search EnergyPlus docs by keyword.
Inputs: query (required), tags, limit, version. Returns: Response from ``search_docs``.
search_objectsARead-onlyIdempotent
Find objects by name or field value substring match.
Inputs: query (required), limit, object_type. Returns: Response from ``search_objects``.
search_schemaARead-onlyIdempotent
Find object types by name or description.
Inputs: query (required), limit, version. Returns: Response from ``search_schema``.
search_weather_stationsBRead-onlyIdempotent
Find weather stations by name or coordinates.
Inputs: limit, query, state, country, +2 more. Returns: Response from ``search_weather_stations``.
update_objectC
Update fields on an existing object.
Inputs: name (required), fields (required), object_type (required).
validate_modelARead-onlyIdempotent
Schema-based pre-flight check — run after any model modifications.
Checks field types, numeric ranges, required fields, enum values, singleton constraints (codes E001-E010, W001-W003), and cross-object reference integrity.
IMPORTANT: This is schema validation only. It does not run EnergyPlus and cannot detect runtime faults such as convergence failures, zone connectivity issues, or autosizing problems. A model that passes this check may still fail to simulate.
Preconditions: model loaded (load_model or new_model). Side effects: none — read-only. Next steps: check_model_integrity for domain-level QA, then save_model, then run_simulation for definitive runtime validation.
Inputs: object_types, check_references. Returns: Response from ``validate_model``.
view_geometryARead-onlyIdempotent
Show interactive 3D building geometry from the loaded model.
Renders detailed building surfaces, fenestration, and shading geometry in a Three.js viewport with orbit controls, placed where EnergyPlus simulates them (zone origins, zone rotations and the building north axis applied). Click surfaces to inspect properties; toggle visibility by surface type or zone. Surfaces that cannot be placed and simplified geometry types (for example Wall:Exterior or Window) are not drawn; they are listed in the payload and in the text summary.
Inputs: color_by.
view_schedulesARead-onlyIdempotent
Show interactive schedule heatmap from the loaded model.
Renders EnergyPlus schedules as a visual heatmap showing hourly values across days of the week (week view) or across the full year (year view). Supports Schedule:Compact, Schedule:Constant, Schedule:Year, and Schedule:File types.
Inputs: name, year.
view_simulation_reportARead-onlyIdempotent
Browse the full EnergyPlus tabular report in an interactive viewer.
Returns all tabular data from the simulation SQL output organized by report, section, and table. The companion viewer provides a searchable, browsable interface with a table-of-contents sidebar.
Requires a completed simulation with SQL output.
Inputs: no named parameters. Returns: Full simulation report for the interactive viewer.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 39 tools
Most tools target a clearly distinct action (add vs batch_add, remove vs remove_objects, validate_model vs check_model_integrity are well-differentiated). A few pairs sit close together — query_timeseries vs export_timeseries, and query_simulation_table vs view_simulation_report — but their descriptions clarify the query/export and data/viewer split.
Nearly all names follow a consistent snake_case verb_noun pattern (add_object, list_objects, run_simulation, view_geometry, download_weather_file). The one outlier is file_manager, a noun-phrase tool with no verb, plus minor verb variety (new_ vs clear_ vs load_), but the convention is largely predictable.
At 39 tools this is well over the comfortable range and could likely be consolidated (e.g. timeseries query/export, report query/view). However the domain genuinely spans model CRUD, schema, docs, validation, simulation, results analysis, weather, and visualization, so the density per functional area (~3-4 tools) is justified.
The surface covers the full EnergyPlus modeling lifecycle: create/load/save/migrate, complete object CRUD plus rename/duplicate, schema and doc introspection, schema and domain-level validation, simulation execution, extensive results analysis, weather retrieval, file management, and visualization. No obvious dead ends for the stated purpose.
Maintenance
Related MCP Connectors
Design, solve and simulate HVAC systems from real components, weather years and buildings.
Heating, ventilation and energy engineering calculations and diagnostics for AI agents.
Edit AutoCAD and Revit MEP drawings from Claude or ChatGPT in plain English.
Solar, weatherization, EV charging, battery and heat-pump decision tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with OpenStudio building energy models through natural language, allowing users to load, inspect, and manipulate OSM files including building geometry, HVAC systems, materials, schedules, and internal loads.11MIT
- AlicenseAqualityBmaintenanceEnables natural-language interaction with Ladybug Tools for building performance simulation, 3D modeling, and data visualization, allowing agents to perform complex environmental analysis tasks without CAD software.312GPL 3.0
- FlicenseNot gradedqualityAmaintenanceEnables natural language interaction with OpenStudio building energy simulation, allowing creation, querying, and modification of models, running EnergyPlus simulations, and analyzing results.58-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to understand, query, and manipulate Honeybee building energy models through natural language via the Model Context Protocol.18GPL 3.0