Skip to main content
Glama
idfkit-mcp

idfkit-mcp

Official
by idfkit

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

Release Build status License

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:IdealLoadsAirSystem accepts, what values are valid, and get links to the official EnergyPlus documentation

  • Search 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.

Documentation | GitHub

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

file_manager (MCP Apps upload UI) and list_files, so clients without a shared filesystem can upload an IDF or epJSON file and load it with load_model(upload_name=...)

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-mcp

Or with uv:

uv add idfkit-mcp

Usage

Run as stdio MCP server (default):

idfkit-mcp

Run as Streamable HTTP MCP server:

idfkit-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Run 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 --version

The server reads these environment variables:

Variable

Default

Effect

IDFKIT_MCP_TRANSPORT

stdio

Default for --transport

IDFKIT_MCP_HOST

127.0.0.1

Default for --host

IDFKIT_MCP_PORT

8000

Default for --port

IDFKIT_MCP_LOG_LEVEL

INFO

Log level for the server and idfkit

IDFKIT_MCP_UPLOAD_DIR

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 install

Commands

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 way

Releasing

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 tools
add_objectA

Add one object. Use batch_add_objects for multiple.

Inputs: object_type (required), name, fields.

analyze_peak_loadsA
Read-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_integrityA
Read-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_sessionA
Destructive

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_idfC
Idempotent

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_typeA
Read-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_fileA
Idempotent

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_timeseriesC
Idempotent

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_referencesA
Read-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_logA
Read-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_sectionA
Read-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_propertiesA
Read-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_objectsA
Read-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_typesA
Read-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_variablesA
Read-onlyIdempotent

List output variables and meters from last simulation.

Inputs: limit, search. Returns: Response from ``list_output_variables``.

list_simulation_reportsA
Read-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_modelA
Idempotent

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_modelA
Destructive

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_tableA
Read-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, EUI

  • SystemSummary — unmet hours, HVAC sizing

  • EnvelopeSummary — U-values, areas, orientations

  • EquipmentSummary — HVAC component sizing

  • ZoneComponentLoadSummary — peak heating/cooling loads by zone

  • LightingSummary — 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_timeseriesB
Read-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_objectA
Destructive

Delete an object. Blocked if referenced unless force=True.

Inputs: name (required), object_type (required), force. Returns: Response from ``remove_object``.

remove_objectsA
Destructive

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_simulationA
Idempotent

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_modelA
Idempotent

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_docsB
Read-onlyIdempotent

Search EnergyPlus docs by keyword.

Inputs: query (required), tags, limit, version. Returns: Response from ``search_docs``.

search_objectsA
Read-onlyIdempotent

Find objects by name or field value substring match.

Inputs: query (required), limit, object_type. Returns: Response from ``search_objects``.

search_schemaA
Read-onlyIdempotent

Find object types by name or description.

Inputs: query (required), limit, version. Returns: Response from ``search_schema``.

search_weather_stationsB
Read-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_modelA
Read-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_geometryA
Read-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_schedulesA
Read-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_reportA
Read-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

    A3.5/5.0

    Scored across 39 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      11
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      3
      12
      GPL 3.0
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables natural language interaction with OpenStudio building energy simulation, allowing creation, querying, and modification of models, running EnergyPlus simulations, and analyzing results.
      58
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to understand, query, and manipulate Honeybee building energy models through natural language via the Model Context Protocol.
      18
      GPL 3.0