io.github.guzz-labs/epwforge-mcp

Official5 toolsLive

by guzz-labs · Python

EPW/DDY weather files - TMY/AMY/CMIP6 morphing, UHI, events, smoke. 3 of 4 tools anon-free.

This MCP server provides AI-agent access to EPWForge for generating, morphing, and downloading weather files used in building energy simulation. It focuses on transforming EPW/DDY inputs into TMY/AMY and other variants, with support for features including UHI, events, and smoke.

🛠️ Key Features

Weather file generation and morphing (EPW, DDY, and CSV outputs)
Station discovery and weather analysis
Charting weather inputs and outputs
Weather file creation for building energy simulation
4 consolidated tools: find_station, analyze_weather, chart_weather, generate_weather_file
Tool set availability described as “3 of 4 tools anon-free”
Version: 0.10.0 (Python)

🚀 Use Cases

Create or morph weather files for energy modeling workflows
Support analyses involving TMY/AMY and future-weather deltas (e.g., CMIP6)
Generate scenarios involving UHI, events, and smoke

⚡ Developer Benefits

MCP server surface mirrored 1:1 via https://epwforge.com/api/mcp
Works with MCP clients such as Claude Web and other hosted MCP clients
Topics include EnergyPlus, OpenStudio, and weather-morphing concepts

⚠️ Limitations

Tool access note: “3 of 4 tools anon-free” (suggests restricted access to one tool)

Topics

ai-agentamybuilding-energy-simulationclaudecmip6energy-modelingenergyplusepwera5future-weatheries-vemcpmcp-servermodel-context-protocolopenstudioclimate-deltasequesttmyxweather-fileweather-morphing

Captured live from the server via tools/list.

find_station

Search the GuzzStations catalog (17,000+ weather stations worldwide, self-hosted mirror of OneBuilding TMYx). Returns matching stations with EPW URLs ready to pass to analyze_weather or chart_weather. Optionally enriches with AMY extreme years (hottest / coldest / most-humid on record) and CMIP6 climate deltas. No auth required.

Parameters10

query	string	optional	Search by city / state (case-insensitive partial match)
lat	number	optional	Latitude — when set, results sorted by proximity
lon	number	optional
country	string	optional	ISO 3-letter country code filter, e.g. 'USA', 'GBR'
max_results	integer	optional	Max stations (default: 10)
include_amy_extremes	boolean	optional	When true and lat+lon are set, also returns the hottest / coldest / most-humid years on record (per ERA5, 1950–present). Useful for picking AMY basis years.
include_climate_deltas	boolean	optional	When true with lat+lon+ssp+year, also returns the monthly CMIP6 delta-T per month and per variable. Lets agents reason about specific shifts before generating files.
ssp	string	optional	SSP scenario (only used with include_climate_deltas). ssp370 is the recommended high-end; ssp585 (SSP5-8.5) is an opt-in extreme stress-test pathway for worst-case analysis.
year	integer	optional	Future horizon (only used with include_climate_deltas)
percentile	integer	optional	Warming percentile (only used with include_climate_deltas, default 50)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search by city / state (case-insensitive partial match)"
    },
    "lat": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Latitude — when set, results sorted by proximity"
    },
    "lon": {
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "country": {
      "type": "string",
      "description": "ISO 3-letter country code filter, e.g. 'USA', 'GBR'"
    },
    "max_results": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Max stations (default: 10)"
    },
    "include_amy_extremes": {
      "type": "boolean",
      "description": "When true and lat+lon are set, also returns the hottest / coldest / most-humid years on record (per ERA5, 1950–present). Useful for picking AMY basis years."
    },
    "include_climate_deltas": {
      "type": "boolean",
      "description": "When true with lat+lon+ssp+year, also returns the monthly CMIP6 delta-T per month and per variable. Lets agents reason about specific shifts before generating files."
    },
    "ssp": {
      "type": "string",
      "enum": [
        "ssp126",
        "ssp245",
        "ssp370",
        "ssp585"
      ],
      "description": "SSP scenario (only used with include_climate_deltas). ssp370 is the recommended high-end; ssp585 (SSP5-8.5) is an opt-in extreme stress-test pathway for worst-case analysis."
    },
    "year": {
      "type": "integer",
      "enum": [
        2030,
        2035,
        2040,
        2045,
        2050,
        2060,
        2070,
        2080,
        2090,
        2100
      ],
      "description": "Future horizon (only used with include_climate_deltas)"
    },
    "percentile": {
      "type": "integer",
      "enum": [
        5,
        10,
        25,
        50,
        75,
        90,
        95
      ],
      "description": "Warming percentile (only used with include_climate_deltas, default 50)"
    }
  }
}

analyze_weather

Compute design conditions, HDD/CDD, monthly stats, and peak heating/cooling days for one or more EPW files. Accepts a `url` (existing EPW), `urls` (compare 2+), or `config` (synthesize on the fly with morphing/UHI/events/smoke). Config mode runs the full generation pipeline server-side but returns only stats — never the EPW content. **Token-saver: pass `compact: true` to get a ~10-field headline response (~100 tokens) instead of the full ~800-token payload.** Use compact for sanity-checking, dashboards, or when chaining many calls; full when you need monthly arrays / peak days / full ASHRAE. Optional `include_full_ashrae` adds ASHRAE 0.4/1/2% cooling + 99.6/99% heating design conditions with mean coincident dewpoint. Optional `include_improbability` (config mode) adds a stress-test score. Optional `include_idf` adds ready-to-paste EnergyPlus SizingPeriod:DesignDay objects. Optional `units` ('imperial' default | 'metric'). **Presentation: when calling with `urls` (multiple files), the response includes a `comparisons` array — render it as a markdown table to the user. Lead with the headline delta, not the raw data.** No auth required; no credits charged.

Parameters8

url	string	optional	EPW URL to analyze (single file)
urls	array	optional	Multiple EPW URLs for comparison (first = baseline). Max 10.
config	object	optional	Synthesize an EPW server-side and analyze it. Stats only — file never returned. lat + lon required. Same morph/UHI/event params as generate_weather_file.
compact	boolean	optional	Return a ~10-field headline-only response (~100 tokens) instead of the full ~800-token payload. Drops monthly arrays, peak days, n_hours, weather_basis blob. Good for sanity checks, dashboards, batched chained calls. Set to false (default) when you need the full payload.
include_full_ashrae	boolean	optional	Add ASHRAE 0.4%/1%/2% cooling DB + 99.6%/99% heating DB design conditions to the response. Free. Ignored when compact=true.
include_improbability	boolean	optional	Add EPWForge's stress-test improbability score (config mode only). Indicates how extreme the synthesized scenario is vs historical baselines.
include_idf	boolean	optional	Add ready-to-paste EnergyPlus SizingPeriod:DesignDay IDF objects to the response. AEC-facing. Ignored when compact=true.
units	string	optional	Output units (default: imperial). When 'metric', temperatures are °C, wind m/s, precip mm, distance km/m.

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "EPW URL to analyze (single file)"
    },
    "urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 2,
      "maxItems": 10,
      "description": "Multiple EPW URLs for comparison (first = baseline). Max 10."
    },
    "config": {
      "type": "object",
      "description": "Synthesize an EPW server-side and analyze it. Stats only — file never returned. lat + lon required. Same morph/UHI/event params as generate_weather_file.",
      "properties": {
        "lat": {
          "type": "number",
          "description": "Latitude, decimal degrees",
          "minimum": -90,
          "maximum": 90
        },
        "lon": {
          "type": "number",
          "description": "Longitude, decimal degrees",
          "minimum": -180,
          "maximum": 180
        },
        "basis": {
          "type": "string",
          "enum": [
            "tmy",
            "amy"
          ],
          "description": "Weather file basis (default: tmy)"
        },
        "amy_year": {
          "type": "integer",
          "description": "Year for AMY basis"
        },
        "ssp": {
          "type": "string",
          "enum": [
            "ssp126",
            "ssp245",
            "ssp370",
            "ssp585"
          ],
          "description": "CMIP6 emission scenario. ssp370 is the recommended high-end for design; ssp585 (SSP5-8.5) is an opt-in extreme stress-test pathway (~4.4°C, low likelihood per IPCC AR6 / CMIP7) for worst-case analysis."
        },
        "year": {
          "type": "integer",
          "enum": [
            2030,
            2035,
            2040,
            2045,
            2050,
            2060,
            2070,
            2080,
            2090,
            2100
          ],
          "description": "Future horizon"
        },
        "percentile": {
          "type": "integer",
          "enum": [
            5,
            10,
            25,
            50,
            75,
            90,
            95
          ],
          "description": "Warming percentile (default: 50)"
        },
        "uhi": {
          "type": "string",
          "enum": [
            "none",
            "suburban",
            "urban",
            "dense_urban"
          ],
          "description": "Urban Heat Island preset"
        },
        "events": {
          "type": "string",
          "description": "Comma-separated events. Valid: heatwave, coldsnap, hothumid, coldwindy. Pairs auto-compound (heat+humid, cold+wind)."
        },
        "event_duration": {
          "type": "integer",
          "minimum": 3,
          "maximum": 30,
          "description": "Event length in days (3-30, default 14). **For stress-test scenarios use 14-21 days** — shorter durations don't capture sustained operational impact (charging schedules, occupancy patterns, equipment cycling). 7 days is too short for any design or resilience analysis. Use 7-10 only for transient short-duration events."
        },
        "intensity": {
          "type": "string",
          "description": "Per-event \"type:1-7\" intensity (1-10 with stress_test=true). 5 = typical extreme, 7 = severe ~50-yr return."
        },
        "intensity_auto": {
          "type": "boolean",
          "description": "Auto-fill unspecified intensities from IPCC AR6 (default: true)"
        },
        "smoke": {
          "type": "boolean",
          "description": "Enable wildfire smoke overlay"
        },
        "smoke_intensity": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10,
          "description": "Smoke severity 1-10 → peak AOD 0.1-6.0"
        },
        "smoke_duration": {
          "type": "integer",
          "minimum": 3,
          "maximum": 30,
          "description": "Smoke days (3-30, default: 7)"
        },
        "tmy_period": {
          "type": "string",
          "enum": [
            "full",
            "2011-2025",
            "2009-2023",
            "2007-2021",
            "2004-2018"
          ],
          "description": "TMYx vintage. Default 2011-2025."
        }
      },
      "required": [
        "lat",
        "lon"
      ]
    },
    "compact": {
      "type": "boolean",
      "description": "Return a ~10-field headline-only response (~100 tokens) instead of the full ~800-token payload. Drops monthly arrays, peak days, n_hours, weather_basis blob. Good for sanity checks, dashboards, batched chained calls. Set to false (default) when you need the full payload."
    },
    "include_full_ashrae": {
      "type": "boolean",
      "description": "Add ASHRAE 0.4%/1%/2% cooling DB + 99.6%/99% heating DB design conditions to the response. Free. Ignored when compact=true."
    },
    "include_improbability": {
      "type": "boolean",
      "description": "Add EPWForge's stress-test improbability score (config mode only). Indicates how extreme the synthesized scenario is vs historical baselines."
    },
    "include_idf": {
      "type": "boolean",
      "description": "Add ready-to-paste EnergyPlus SizingPeriod:DesignDay IDF objects to the response. AEC-facing. Ignored when compact=true."
    },
    "units": {
      "type": "string",
      "enum": [
        "imperial",
        "metric"
      ],
      "description": "Output units (default: imperial). When 'metric', temperatures are °C, wind m/s, precip mm, distance km/m."
    }
  }
}

chart_weather

Render an SVG chart from EPW data. Eight chart types: `diurnal` (~10 KB, monthly hourly profile), `temp_carpet` (heatmap of hour × day-of-year — ~30 KB preview / ~150 KB full), `wind_rose` (~12 KB, polar bars by direction × speed), `monthly_boxplot` (~6 KB, Q1/median/Q3 + whiskers per month), `utci_carpet` (~90 KB, outdoor heat-stress hour × day, colored by UTCI category — Bröde 2012, shaded Tmrt), `economizer_carpet` (~90 KB, air-side economizer free / integrated / locked-out hour × day under ASHRAE 90.1 high-limit), `pv_tilt_azimuth` (~60 KB, annual PV generation across full tilt × azimuth space, isotropic-sky POA at lat from EPW header — optimum orientation marked), `solar_under_events` (~12 KB, weekly GHI of the modified scenario vs the no-overlay reference; bands color event-affected weeks. Requires `config` — server runs the pipeline twice, with and without overlays), `comparison` (~10 KB, design-condition deltas across EPWs). Accepts `url` (single), `urls` (2+ for comparison), or `config` (synthesize on the fly). Config mode is anon-safe — runs pipeline, returns SVG only. No auth required. **Token budget**: SVGs are returned inline by default. Large outputs (>50 KB) auto-upload to Blob storage (when configured) and return a URL instead, keeping your context lean. Always check `svg_size_kb` in the response. **Presentation: when handing the chart to the user, just link or embed it — don't narrate what's in it. Let the chart speak.**

Parameters10

url	string	optional	EPW URL (single-EPW charts: diurnal, temp_carpet, wind_rose, monthly_boxplot, utci_carpet, economizer_carpet, pv_tilt_azimuth)
urls	array	optional	EPW URLs for chart_type=comparison (first = baseline)
config	object	optional	Synthesize an EPW and chart it. Same params as generate_weather_file. SVG only — no file delivery.
chart_type	string	optional	Default: diurnal
resolution	string	optional	temp_carpet only. 'preview' (default) ~30 KB with 32 color buckets — visually identical at typical render sizes. 'full' ~150 KB with per-cell rgb() — use only when saving to file or when you specifically need exact color fidelity.
econ_mode	string	optional	economizer_carpet only. 'drybulb' (default) limits OA by Tdb; 'enthalpy' limits by moist-air enthalpy — more honest in humid climates (captures latent load).
econ_high_limit_f	number	optional	economizer_carpet only. ASHRAE 90.1 high-limit shutoff. Defaults: 75°F (drybulb mode) or 28 BTU/lb (enthalpy mode).
econ_supply_air_f	number	optional	economizer_carpet only. Supply-air temperature setpoint (°F). Default 55.
pv_tilt	number	optional	pv_tilt_azimuth only. Optional — marks the user's planned tilt (deg, 0=horizontal) on the heatmap alongside the optimum.
pv_azimuth	number	optional	pv_tilt_azimuth only. Optional — marks the user's planned compass azimuth (deg, 0=N, 180=S) on the heatmap.

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "EPW URL (single-EPW charts: diurnal, temp_carpet, wind_rose, monthly_boxplot, utci_carpet, economizer_carpet, pv_tilt_azimuth)"
    },
    "urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 2,
      "maxItems": 10,
      "description": "EPW URLs for chart_type=comparison (first = baseline)"
    },
    "config": {
      "type": "object",
      "description": "Synthesize an EPW and chart it. Same params as generate_weather_file. SVG only — no file delivery.",
      "properties": {
        "lat": {
          "type": "number",
          "description": "Latitude, decimal degrees",
          "minimum": -90,
          "maximum": 90
        },
        "lon": {
          "type": "number",
          "description": "Longitude, decimal degrees",
          "minimum": -180,
          "maximum": 180
        },
        "basis": {
          "type": "string",
          "enum": [
            "tmy",
            "amy"
          ],
          "description": "Weather file basis (default: tmy)"
        },
        "amy_year": {
          "type": "integer",
          "description": "Year for AMY basis"
        },
        "ssp": {
          "type": "string",
          "enum": [
            "ssp126",
            "ssp245",
            "ssp370",
            "ssp585"
          ],
          "description": "CMIP6 emission scenario. ssp370 is the recommended high-end for design; ssp585 (SSP5-8.5) is an opt-in extreme stress-test pathway (~4.4°C, low likelihood per IPCC AR6 / CMIP7) for worst-case analysis."
        },
        "year": {
          "type": "integer",
          "enum": [
            2030,
            2035,
            2040,
            2045,
            2050,
            2060,
            2070,
            2080,
            2090,
            2100
          ],
          "description": "Future horizon"
        },
        "percentile": {
          "type": "integer",
          "enum": [
            5,
            10,
            25,
            50,
            75,
            90,
            95
          ],
          "description": "Warming percentile (default: 50)"
        },
        "uhi": {
          "type": "string",
          "enum": [
            "none",
            "suburban",
            "urban",
            "dense_urban"
          ],
          "description": "Urban Heat Island preset"
        },
        "events": {
          "type": "string",
          "description": "Comma-separated events. Valid: heatwave, coldsnap, hothumid, coldwindy. Pairs auto-compound (heat+humid, cold+wind)."
        },
        "event_duration": {
          "type": "integer",
          "minimum": 3,
          "maximum": 30,
          "description": "Event length in days (3-30, default 14). **For stress-test scenarios use 14-21 days** — shorter durations don't capture sustained operational impact (charging schedules, occupancy patterns, equipment cycling). 7 days is too short for any design or resilience analysis. Use 7-10 only for transient short-duration events."
        },
        "intensity": {
          "type": "string",
          "description": "Per-event \"type:1-7\" intensity (1-10 with stress_test=true). 5 = typical extreme, 7 = severe ~50-yr return."
        },
        "intensity_auto": {
          "type": "boolean",
          "description": "Auto-fill unspecified intensities from IPCC AR6 (default: true)"
        },
        "smoke": {
          "type": "boolean",
          "description": "Enable wildfire smoke overlay"
        },
        "smoke_intensity": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10,
          "description": "Smoke severity 1-10 → peak AOD 0.1-6.0"
        },
        "smoke_duration": {
          "type": "integer",
          "minimum": 3,
          "maximum": 30,
          "description": "Smoke days (3-30, default: 7)"
        },
        "tmy_period": {
          "type": "string",
          "enum": [
            "full",
            "2011-2025",
            "2009-2023",
            "2007-2021",
            "2004-2018"
          ],
          "description": "TMYx vintage. Default 2011-2025."
        }
      },
      "required": [
        "lat",
        "lon"
      ]
    },
    "chart_type": {
      "type": "string",
      "enum": [
        "diurnal",
        "temp_carpet",
        "wind_rose",
        "monthly_boxplot",
        "utci_carpet",
        "economizer_carpet",
        "pv_tilt_azimuth",
        "solar_under_events",
        "comparison"
      ],
      "description": "Default: diurnal"
    },
    "resolution": {
      "type": "string",
      "enum": [
        "preview",
        "full"
      ],
      "description": "temp_carpet only. 'preview' (default) ~30 KB with 32 color buckets — visually identical at typical render sizes. 'full' ~150 KB with per-cell rgb() — use only when saving to file or when you specifically need exact color fidelity."
    },
    "econ_mode": {
      "type": "string",
      "enum": [
        "drybulb",
        "enthalpy"
      ],
      "description": "economizer_carpet only. 'drybulb' (default) limits OA by Tdb; 'enthalpy' limits by moist-air enthalpy — more honest in humid climates (captures latent load)."
    },
    "econ_high_limit_f": {
      "type": "number",
      "description": "economizer_carpet only. ASHRAE 90.1 high-limit shutoff. Defaults: 75°F (drybulb mode) or 28 BTU/lb (enthalpy mode)."
    },
    "econ_supply_air_f": {
      "type": "number",
      "description": "economizer_carpet only. Supply-air temperature setpoint (°F). Default 55."
    },
    "pv_tilt": {
      "type": "number",
      "description": "pv_tilt_azimuth only. Optional — marks the user's planned tilt (deg, 0=horizontal) on the heatmap alongside the optimum."
    },
    "pv_azimuth": {
      "type": "number",
      "description": "pv_tilt_azimuth only. Optional — marks the user's planned compass azimuth (deg, 0=N, 180=S) on the heatmap."
    }
  }
}

explore_design_conditions

Interactive single-site design-conditions explorer. Returns full ASHRAE design conditions + diurnal chart for the requested scenario. In MCP Apps-capable hosts (Claude Desktop, ChatGPT, VS Code, Goose), the response renders as a widget with sliders for SSP / year / percentile / UHI — dragging a slider re-calls this tool live. Use when a user wants to interactively tune a single site. For multi-site comparison, use analyze_weather(urls=[...]) instead. Defaults to present-day TMY (no morph) — pass ssp+year for future scenarios. P75 default percentile is design-realistic; P50 underestimates the tail. No auth required.

Parameters7

lat	number	required	Latitude, decimal degrees
lon	number	required	Longitude, decimal degrees
ssp	string	optional	CMIP6 emission scenario. Omit for present-day TMY. ssp370 is the recommended high-end; ssp585 (SSP5-8.5) is an opt-in extreme stress-test pathway for worst-case analysis.
year	integer	optional	Future horizon. Pair with ssp.
percentile	integer	optional	Warming percentile. P75 design-realistic; P50 median.
uhi	string	optional	Urban Heat Island preset
allow_custom_location	boolean	optional	Required when no OneBuilding station within 50 km

Raw schema

{
  "type": "object",
  "properties": {
    "lat": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Latitude, decimal degrees"
    },
    "lon": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "Longitude, decimal degrees"
    },
    "ssp": {
      "type": "string",
      "enum": [
        "ssp126",
        "ssp245",
        "ssp370",
        "ssp585"
      ],
      "description": "CMIP6 emission scenario. Omit for present-day TMY. ssp370 is the recommended high-end; ssp585 (SSP5-8.5) is an opt-in extreme stress-test pathway for worst-case analysis."
    },
    "year": {
      "type": "integer",
      "enum": [
        2030,
        2035,
        2040,
        2045,
        2050,
        2060,
        2070,
        2080,
        2090,
        2100
      ],
      "description": "Future horizon. Pair with ssp."
    },
    "percentile": {
      "type": "integer",
      "minimum": 5,
      "maximum": 95,
      "description": "Warming percentile. P75 design-realistic; P50 median."
    },
    "uhi": {
      "type": "string",
      "enum": [
        "none",
        "suburban",
        "urban",
        "dense_urban"
      ],
      "description": "Urban Heat Island preset"
    },
    "allow_custom_location": {
      "type": "boolean",
      "description": "Required when no OneBuilding station within 50 km"
    }
  },
  "required": [
    "lat",
    "lon"
  ]
}

generate_weather_file

Generate and deliver an EPW or DDY file. The only paid tool — charges credits per call: 1 for a single file, 2 for a 4-file scenarios batch, 10 for a per-model CMIP6 ensemble. Requires auth (Bearer API key or OAuth). Free tier: 5 welcome credits at signup. For preview/analysis without download, use analyze_weather or chart_weather with `config` instead.

Parameters21

lat	number	required	Latitude, decimal degrees
lon	number	required	Longitude, decimal degrees
basis	string	optional	Weather file basis (default: tmy)
amy_year	integer	optional	Year for AMY basis
ssp	string	optional	CMIP6 emission scenario. ssp370 is the recommended high-end for design; ssp585 (SSP5-8.5) is an opt-in extreme stress-test pathway (~4.4°C, low likelihood per IPCC AR6 / CMIP7) for worst-case analysis.
year	integer	optional	Future horizon
percentile	integer	optional	Warming percentile (default: 50)
uhi	string	optional	Urban Heat Island preset
events	string	optional	Comma-separated events. Valid: heatwave, coldsnap, hothumid, coldwindy. Pairs auto-compound (heat+humid, cold+wind).
event_duration	integer	optional	Event length in days (3-30, default 14). For stress-test scenarios use 14-21 days — shorter durations don't capture sustained operational impact (charging schedules, occupancy patterns, equipment cycling). 7 days is too short for any design or resilience analysis. Use 7-10 only for transient short-duration events.
intensity	string	optional	Per-event "type:1-7" intensity (1-10 with stress_test=true). 5 = typical extreme, 7 = severe ~50-yr return.
intensity_auto	boolean	optional	Auto-fill unspecified intensities from IPCC AR6 (default: true)
smoke	boolean	optional	Enable wildfire smoke overlay
smoke_intensity	integer	optional	Smoke severity 1-10 → peak AOD 0.1-6.0
smoke_duration	integer	optional	Smoke days (3-30, default: 7)
tmy_period	string	optional	TMYx vintage. Default 2011-2025.
format	string	optional	Output format (default: epw)
ensemble	boolean	optional	Generate a per-model CMIP6 ensemble (~20 EPWs, one per climate model). Costs 10 credits. Requires ssp + year.
scenarios	array	optional	Batch mode — array of configs, each generated in parallel. Same shape as the top-level config. When set, top-level config params are ignored. Costs 1 credit per scenario (up to 10).
stress_test	boolean	optional	Unlock intensity 8-10. Default false.
include_ddy	boolean	optional	When format=epw, also include the matching DDY in the response (single-file only).

Raw schema

{
  "type": "object",
  "properties": {
    "lat": {
      "type": "number",
      "description": "Latitude, decimal degrees",
      "minimum": -90,
      "maximum": 90
    },
    "lon": {
      "type": "number",
      "description": "Longitude, decimal degrees",
      "minimum": -180,
      "maximum": 180
    },
    "basis": {
      "type": "string",
      "enum": [
        "tmy",
        "amy"
      ],
      "description": "Weather file basis (default: tmy)"
    },
    "amy_year": {
      "type": "integer",
      "description": "Year for AMY basis"
    },
    "ssp": {
      "type": "string",
      "enum": [
        "ssp126",
        "ssp245",
        "ssp370",
        "ssp585"
      ],
      "description": "CMIP6 emission scenario. ssp370 is the recommended high-end for design; ssp585 (SSP5-8.5) is an opt-in extreme stress-test pathway (~4.4°C, low likelihood per IPCC AR6 / CMIP7) for worst-case analysis."
    },
    "year": {
      "type": "integer",
      "enum": [
        2030,
        2035,
        2040,
        2045,
        2050,
        2060,
        2070,
        2080,
        2090,
        2100
      ],
      "description": "Future horizon"
    },
    "percentile": {
      "type": "integer",
      "enum": [
        5,
        10,
        25,
        50,
        75,
        90,
        95
      ],
      "description": "Warming percentile (default: 50)"
    },
    "uhi": {
      "type": "string",
      "enum": [
        "none",
        "suburban",
        "urban",
        "dense_urban"
      ],
      "description": "Urban Heat Island preset"
    },
    "events": {
      "type": "string",
      "description": "Comma-separated events. Valid: heatwave, coldsnap, hothumid, coldwindy. Pairs auto-compound (heat+humid, cold+wind)."
    },
    "event_duration": {
      "type": "integer",
      "minimum": 3,
      "maximum": 30,
      "description": "Event length in days (3-30, default 14). **For stress-test scenarios use 14-21 days** — shorter durations don't capture sustained operational impact (charging schedules, occupancy patterns, equipment cycling). 7 days is too short for any design or resilience analysis. Use 7-10 only for transient short-duration events."
    },
    "intensity": {
      "type": "string",
      "description": "Per-event \"type:1-7\" intensity (1-10 with stress_test=true). 5 = typical extreme, 7 = severe ~50-yr return."
    },
    "intensity_auto": {
      "type": "boolean",
      "description": "Auto-fill unspecified intensities from IPCC AR6 (default: true)"
    },
    "smoke": {
      "type": "boolean",
      "description": "Enable wildfire smoke overlay"
    },
    "smoke_intensity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Smoke severity 1-10 → peak AOD 0.1-6.0"
    },
    "smoke_duration": {
      "type": "integer",
      "minimum": 3,
      "maximum": 30,
      "description": "Smoke days (3-30, default: 7)"
    },
    "tmy_period": {
      "type": "string",
      "enum": [
        "full",
        "2011-2025",
        "2009-2023",
        "2007-2021",
        "2004-2018"
      ],
      "description": "TMYx vintage. Default 2011-2025."
    },
    "format": {
      "type": "string",
      "enum": [
        "epw",
        "ddy"
      ],
      "description": "Output format (default: epw)"
    },
    "ensemble": {
      "type": "boolean",
      "description": "Generate a per-model CMIP6 ensemble (~20 EPWs, one per climate model). Costs 10 credits. Requires ssp + year."
    },
    "scenarios": {
      "type": "array",
      "maxItems": 10,
      "description": "Batch mode — array of configs, each generated in parallel. Same shape as the top-level config. When set, top-level config params are ignored. Costs 1 credit per scenario (up to 10).",
      "items": {
        "type": "object",
        "properties": {
          "lat": {
            "type": "number",
            "description": "Latitude, decimal degrees",
            "minimum": -90,
            "maximum": 90
          },
          "lon": {
            "type": "number",
            "description": "Longitude, decimal degrees",
            "minimum": -180,
            "maximum": 180
          },
          "basis": {
            "type": "string",
            "enum": [
              "tmy",
              "amy"
            ],
            "description": "Weather file basis (default: tmy)"
          },
          "amy_year": {
            "type": "integer",
            "description": "Year for AMY basis"
          },
          "ssp": {
            "type": "string",
            "enum": [
              "ssp126",
              "ssp245",
              "ssp370",
              "ssp585"
            ],
            "description": "CMIP6 emission scenario. ssp370 is the recommended high-end for design; ssp585 (SSP5-8.5) is an opt-in extreme stress-test pathway (~4.4°C, low likelihood per IPCC AR6 / CMIP7) for worst-case analysis."
          },
          "year": {
            "type": "integer",
            "enum": [
              2030,
              2035,
              2040,
              2045,
              2050,
              2060,
              2070,
              2080,
              2090,
              2100
            ],
            "description": "Future horizon"
          },
          "percentile": {
            "type": "integer",
            "enum": [
              5,
              10,
              25,
              50,
              75,
              90,
              95
            ],
            "description": "Warming percentile (default: 50)"
          },
          "uhi": {
            "type": "string",
            "enum": [
              "none",
              "suburban",
              "urban",
              "dense_urban"
            ],
            "description": "Urban Heat Island preset"
          },
          "events": {
            "type": "string",
            "description": "Comma-separated events. Valid: heatwave, coldsnap, hothumid, coldwindy. Pairs auto-compound (heat+humid, cold+wind)."
          },
          "event_duration": {
            "type": "integer",
            "minimum": 3,
            "maximum": 30,
            "description": "Event length in days (3-30, default 14). **For stress-test scenarios use 14-21 days** — shorter durations don't capture sustained operational impact (charging schedules, occupancy patterns, equipment cycling). 7 days is too short for any design or resilience analysis. Use 7-10 only for transient short-duration events."
          },
          "intensity": {
            "type": "string",
            "description": "Per-event \"type:1-7\" intensity (1-10 with stress_test=true). 5 = typical extreme, 7 = severe ~50-yr return."
          },
          "intensity_auto": {
            "type": "boolean",
            "description": "Auto-fill unspecified intensities from IPCC AR6 (default: true)"
          },
          "smoke": {
            "type": "boolean",
            "description": "Enable wildfire smoke overlay"
          },
          "smoke_intensity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "description": "Smoke severity 1-10 → peak AOD 0.1-6.0"
          },
          "smoke_duration": {
            "type": "integer",
            "minimum": 3,
            "maximum": 30,
            "description": "Smoke days (3-30, default: 7)"
          },
          "tmy_period": {
            "type": "string",
            "enum": [
              "full",
              "2011-2025",
              "2009-2023",
              "2007-2021",
              "2004-2018"
            ],
            "description": "TMYx vintage. Default 2011-2025."
          },
          "label": {
            "type": "string"
          }
        },
        "required": [
          "lat",
          "lon"
        ]
      }
    },
    "stress_test": {
      "type": "boolean",
      "description": "Unlock intensity 8-10. Default false."
    },
    "include_ddy": {
      "type": "boolean",
      "description": "When format=epw, also include the matching DDY in the response (single-file only)."
    }
  },
  "required": [
    "lat",
    "lon"
  ]
}

README.md11 KBView on GitHub

epwforge-mcp

MCP server for EPWForge — give Claude, Cursor, and other AI agents the ability to generate, morph, and download weather files for building energy simulation.

Status: 0.10.0 (Python). Four consolidated tools — find_station, analyze_weather, chart_weather, generate_weather_file. Production backend, all tier features wired in. Mirrored 1:1 by the hosted MCP at https://epwforge.com/api/mcp (Claude Web / hosted MCP clients get the same surface).

What is EPWForge?

EPWForge generates and morphs weather files (.epw, .ddy, .csv) for building energy simulation tools — EnergyPlus, OpenStudio, IES VE, eQUEST, and any workflow that consumes EPW. The platform supports:

TMYx generation anywhere — typical meteorological years synthesized from ERA5 reanalysis (1950–present) for any global lat/lon, or passthrough of published OneBuilding TMYx files for ~17,000 known stations.
AMY (Actual Meteorological Year) — historical hourly weather for any specific year since 1950. Useful for stress-testing against observed extremes.
CMIP6 climate morphing — apply SSP1-2.6 / SSP2-4.5 / SSP3-7.0 at horizons 2030–2100 across 7 warming percentiles, plus SSP5-8.5 as an opt-in extreme stress test. SSP3-7.0 is the recommended high-end for design. Belcher 2005 mean-shift hybridised with UKCP18 / NOAA Atlas 14 diurnal anomalies.
Urban Heat Island adjustment — Stewart & Oke 2012 Local Climate Zone presets (suburban / urban / dense_urban).
Extreme event injection — heatwave, cold snap, hot-humid, cold-windy, wildfire smoke. Per-event intensity 1–10, AR6-auto-fill under an SSP. Events stitched at the baseline's hottest / coldest 14-day window.
ASHRAE 169 design conditions — full percentile bins (0.4 / 1 / 2 cooling, 99.6 / 99 heating, WB / DP / Enth variants), computed from the modified hourly distribution.
Output formats — EnergyPlus (.epw + .ddy + .stat), CSV hourly, PVsyst, ESP-r .clm. Bundled .zip available.

Tools

Four consolidated tools. Operations that were once separate tools (batch, ensemble, design-day, etc.) are now parameters on these four — see the deprecation map below.

Tool	What it does	Auth
`find_station`	Search the ~17,000-station GuzzStations catalog by name, country, or coordinates. Optional `compact=True` returns just the newest TMYx per station (6–10× smaller responses for chained agent workflows).	none
`analyze_weather`	Statistical summary of an EPW. Three modes: `url=` (single file), `urls=[]` (2–10 file comparison), `config={...}` (synthesize a morphed scenario from lat/lon — no EPW content returned). Optional `include_full_ashrae`, `include_improbability`, `include_idf`.	none
`chart_weather`	Inline SVG chart. Single-EPW types: `diurnal`, `temp_carpet`, `wind_rose`, `monthly_boxplot`, `utci_carpet`, `economizer_carpet`, `pv_tilt_azimuth`, `solar_under_events`. Multi-EPW type: `comparison`.	none
`generate_weather_file`	Generate and return a downloadable weather file with the full morph stack. Format = `epw` / `ddy` / `csv` / `zip` / `pvsyst`. Supports `ensemble=true` (all SSPs at once).	API key + credits

Deprecation map (v0.2.0 consolidation)

Migrating from a pre-0.2.0 agent script? Old → new:

Old tool	Now reached via
`generate_design_day`	`generate_weather_file(format="ddy")`
`generate_ensemble`	`generate_weather_file(ensemble=true)`
`generate_batch`	Loop `generate_weather_file` client-side, or `generate_weather_file(scenarios=[...])`
`get_station_epw`	Pass the `epw_url` from `find_station` to `analyze_weather` / `chart_weather`, or download directly
`analyze_epw`	`analyze_weather(url=...)`
`compare_scenarios`	`analyze_weather(config={...})` per scenario, or `analyze_weather(urls=[...])` for static EPWs
`chart_diurnal_profile`	`chart_weather(url=..., chart_type="diurnal")`
`chart_compare_scenarios`	`chart_weather(urls=[...], chart_type="comparison")`
`explore_design_conditions`	Removed in v0.9.0. Functionality being folded into `analyze_weather` with a scenario-grid widget (Phase 3 redesign — see brain-central notes).

Full reference

The canonical reference lives on the EPWForge site:

epwforge.com/docs — every parameter, example call, error codes, methodology references, validation numbers.
Tool docstrings in python/src/epwforge_mcp/server.py — read-it-in-IDE source of truth, lifted into the docs page above.
tools/list on the running server — most accurate, reflects the exact version installed.

Quick examples

python

# Find the nearest station to a coordinate, with token-efficient response
find_station(lat=40.71, lon=-74.01, compact=True)

# Analyze a published TMYx file
analyze_weather(url="https://.../USA_NY_New.York-JFK.AP.744860_TMYx.2011-2025.epw")

# Compare cooling design conditions across 3 cities
analyze_weather(urls=["...A.epw", "...B.epw", "...C.epw"])

# Synthesize a stress-test scenario at any lat/lon (no auth needed — no EPW content returned)
analyze_weather(
    config={
        "lat": 40.71, "lon": -74.01,
        "ssp": "ssp370", "year": 2050, "percentile": 75,
        "uhi": "urban",
        "events": "heatwave",
        "intensity": "heatwave:6",
        "event_duration": 14,
    },
    include_full_ashrae=True,
    include_improbability=True,
)

# Inline SVG chart (zero context cost vs base64 PNG)
chart_weather(url="https://.../...epw", chart_type="temp_carpet")

# Generate the actual downloadable file (auth + credits)
generate_weather_file(
    lat=40.71, lon=-74.01,
    format="zip",       # EPW + DDY + STAT bundled
    ssp="ssp370", year=2090, percentile=90,
    uhi="urban",
    events="heatwave,hothumid", event_duration=14,
    smoke_enabled=True, smoke_intensity=5,
)

Install

bash

pip install epwforge-mcp
# or, with uv:
uvx epwforge-mcp

Requires Python ≥ 3.10.

Connecting to Claude / Cursor / other MCP clients

Add to your MCP client config (Claude Desktop's claude_desktop_config.json, Cursor's MCP settings, VS Code's MCP extension, Goose):

json

{
  "mcpServers": {
    "epwforge": {
      "command": "epwforge-mcp",
      "env": {
        "EPWFORGE_API_KEY": "sk_live_..."
      }
    }
  }
}

Get an API key (free or paid) at epwforge.com/account. Read-only tools (find_station, analyze_weather, chart_weather) work without a key; only generate_weather_file requires one.

For browser-based MCP clients (Claude Web, ChatGPT, etc.), use the hosted endpoint:

code

https://epwforge.com/api/mcp

Credits & pricing

Credit-based. Every plan gets every feature; credits gate volume.

Plan	Price	Credits/mo	$/credit
Free	$0	5 lifetime	n/a
Starter	$49	10	$4.90
Pro	$149	50	$2.98
Pro+	$249	100	$2.49

One-time top-up packs available: 5 cr / $50, 20 cr / $180, 50 cr / $400.

Tool call	Cost
`find_station`, `analyze_weather`, `chart_weather`	0 credits (no auth needed)
`generate_weather_file` — single file (epw / ddy / csv / pvsyst)	1 credit
`generate_weather_file` — bundle (zip with 4+ files, AMY, all-SSP)	2 credits
`generate_weather_file` — CMIP6 ensemble (per-model)	10 credits

Out-of-credits returns HTTP 402 with hints pointing at top-up packs and subscription upgrades. The MCP surfaces 402s as ToolError with a hint field; in agent loops this naturally routes the user to the upgrade flow.

Environment variables

Variable	Purpose	Default
`EPWFORGE_API_KEY`	Bearer token for `generate_weather_file`	none — read-only tools work without
`EPWFORGE_BASE_URL`	Override the API host (mainly for testing against a local backend)	`https://epwforge.com`

Behavior notes

Anon-safe by construction. find_station, analyze_weather, and chart_weather never return EPW content; config-mode analyze_weather synthesizes the morphed scenario server-side and returns only stats. Only generate_weather_file touches credits / auth.
agent_guidance field. Most responses include a short, judgment-shaping string the model can use to choose the right next step (e.g. "nearest station is 8 km — use it directly" vs "nearest station is 250 km — consider config-mode synthesis").
Inline SVG charts rather than base64 PNG — typically 10× smaller in context. Each chart's svg_size_kb is reported up-front so agents can self-budget. Charts >50 KB auto-upload to Vercel Blob and return svg_url instead.
Compound events. events="heatwave,hothumid" blends hothumid's humidity onto the heatwave at 50%. events="coldsnap,coldwindy" blends wind onto the cold snap. Secondary folds into the primary stitch — not stitched separately.
Event placement. Events anchor at the cell's hottest day (heat family) or coldest day (cold family), then center for the requested duration. The peak day's diurnal cycle is sustained across the event — a 30-day request gets 30 days of peak heat, not a stretched 14-day shape.
AR6 SSP auto-fill. With an SSP active, unspecified event intensities auto-fill from IPCC AR6 ensemble factors for the cell's region. Cold-family events stay at intensity 5 (no future amplification) because recent observations don't yet support the AR6 ensemble's cold-side dampening. Pass intensity_auto=false to disable.

Development

bash

git clone https://github.com/guzz-labs/epwforge-mcp
cd epwforge-mcp/python
uv sync
uv run epwforge-mcp   # runs the stdio server

Run tests:

bash

.venv/bin/python -m pytest tests/ -v   # 30+ tests

Test against a local API:

bash

EPWFORGE_BASE_URL=http://localhost:3000 \
EPWFORGE_API_KEY=sk_live_... \
uv run epwforge-mcp

Version sync (before publishing):

bash

python3 scripts/check-versions.py            # verify all 5 version strings agree
python3 scripts/check-versions.py --set 0.9.3 # bump everywhere atomically

License

MIT

Install

Tools (5)

find_stationanalyze_weatherchart_weatherexplore_design_conditionsgenerate_weather_file

Configuration

Environment variables

EPWFORGE_API_KEYsecret

EPWForge API key — only required for generate_weather_file. Find/analyze/chart tools work without it. Generate a free key (any tier) at https://epwforge.com/account.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "epwforge-mcp": {
      "command": "uvx",
      "args": [
        "epwforge-mcp"
      ],
      "env": {
        "EPWFORGE_API_KEY": "<YOUR_EPWFORGE_API_KEY>"
      }
    }
  }
}

io.github.guzz-labs/epwforge-mcp

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

find_station

analyze_weather

chart_weather

explore_design_conditions

generate_weather_file

epwforge-mcp

What is EPWForge?

Tools

Deprecation map (v0.2.0 consolidation)

Full reference

Quick examples

Install

Connecting to Claude / Cursor / other MCP clients

Credits & pricing

Environment variables

Behavior notes

Development

Links

License

Install

Configuration

Related servers