Epwforge

Name: Epwforge
Author: guzz-labs

@guzz-labs

About Epwforge

Weather files (EPW/DDY) for building energy simulation. Search 17,000+ stations, analyze any EPW, render charts (diurnal/wind rose/temp carpet/monthly boxplot), generate TMY/AMY/CMIP6-morphed scenarios with UHI/extreme events/wildfire smoke + EnergyPlus DesignDay IDF. 3 of 4 tool

#weather #climate #building-energy #simulation #energyplus #cmip6 #epw #ddy #ashrae #aec

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "epwforge": {
      "command": "uvx",
      "args": [
        "[email protected]"
      ],
      "env": {
        "EPWFORGE_API_KEY": "<YOUR_API_KEY_OPTIONAL>"
      }
    }
  }
}

Tools

Search the GuzzStations catalog (17,000+ weather stations worldwide). Optional enrichments (route through hosted MCP for the extra queries): - include_amy_extremes: hottest/coldest/most-humid years on record - include_climate_deltas: monthly CMIP6 delta-T for the picked scenario No authentication required for any mode. Examples: find_station(query="Denver") find_station(lat=40.7, lon=-74.0, max_results=5) find_station(country="JPN", query="Tokyo") find_station(lat=40.7, lon=-74.0, include_amy_extremes=True) find_station(lat=40.7, lon=-74.0, include_climate_deltas=True, ssp="ssp245", year=2050)

Compute design conditions, HDD/CDD, monthly stats, and peak days for one or more EPW files. No EPW content returned — stats only. Three modes: 1. Single URL: analyze_weather(url="https://...") 2. Multi-URL comparison: analyze_weather(urls=["...", "...", "..."]) 3. Synthesized config: analyze_weather(config={"lat": 40.7, "lon": -74, "ssp": "ssp585", "year": 2050, "uhi": "urban"}) Modes 1 + 2 download the URLs and parse locally (purely client-side). Mode 3 routes through the hosted EPWForge MCP so the morph/UHI/event/smoke pipeline runs on EPWForge infrastructure — the synthesized EPW never leaves the server. Use mode 3 to preview a future-climate scenario or a UHI / extreme-event sensitivity without spending credits. No authentication required for any mode.

Render an SVG chart from EPW data. chart_type='diurnal' — monthly Max / Avg / Min hourly temperature profile in °F (January and July highlighted, annual mean overlaid). Pass `url` or `config`. chart_type='comparison' — horizontal-bar chart of cooling/heating deltas across multiple EPWs. Pass `urls` (first = baseline). No authentication required for any mode.

Generate and deliver an EPW or DDY file. Requires an EPWFORGE_API_KEY. Charges credits per call: 1 for single, 1×N for scenarios batch, 10 for ensemble. Free signup at https://epwforge.com includes 5 welcome credits. Three modes: 1. Single file (default): generate_weather_file(lat=40.7, lon=-74, ssp="ssp245", year=2050) 2. Batch (1×N): generate_weather_file(scenarios=[{lat, lon, ssp:...}, ...]) 3. Ensemble (10 credits): generate_weather_file(lat=, lon=, ssp=, year=, ensemble=True) — returns ~20 per-model EPWs For analysis / charts without paying credits, use analyze_weather or chart_weather with a `config` argument — same morph/UHI/event pipeline, stats/SVG returned, no EPW delivered.

Overview

What is Epwforge?

Epwforge is an MCP server that gives Claude, Cursor, and other AI agents the ability to generate, morph, and download weather files (.epw, .ddy) for building energy simulation tools like EnergyPlus, OpenStudio, IES VE, and eQUEST. It integrates with the EPWForge platform, allowing agents to produce custom TMYx, actual meteorological years, future‑climate (CMIP6) morphs, urban heat island adjustments, extreme events, and wildfire smoke overlays.

How to use Epwforge?

Install the Python package (pip install epwforge-mcp) and add a epwforge entry to your MCP client config (e.g., claude_desktop_config.json), pointing to the epwforge-mcp command and supplying your EPWFORGE_API_KEY. The server provides ten tools; most agents will call find_station to discover available stations, then either get_station_epw for a published TMYx file or generate_weather_file for a custom synthesized one.

Key features of Epwforge

Synthesize custom weather files from ERA5 reanalysis at any global lat/lon.
Fetch published TMYx files from the OneBuilding/GuzzStations library.
Apply CMIP6 future‑climate morphing with SSP scenarios and warming percentiles.
Inject extreme events — heat waves, cold snaps, humidity, wind, and wildfire smoke.
Generate design‑day (DDY) files for EnergyPlus sizing.
Run batch and ensemble generation for multi‑scenario analysis.
Analyze and compare EPWs inline without creating new files.
Render SVG charts of diurnal profiles and scenario deltas.

Use cases of Epwforge

Generate a worst‑case future climate EPW for a building at a specific lat/lon with SSP3‑7.0, urban heat island, and a 14‑day heat wave.
Fetch the latest published TMYx file for an airport station to use in a compliance submittal.
Create a 10‑member ensemble of per‑model CMIP6 morphed EPWs for inter‑model uncertainty analysis.
Run a sensitivity sweep comparing up to 10 scenarios (e.g., different SSPs and percentiles) and view results as a delta chart.
Quickly analyze an existing EPW file’s design conditions, degree‑days, and monthly temperature shape.

FAQ from Epwforge

What is the difference between `generate_weather_file` and `get_station_epw`?

generate_weather_file synthesizes a custom EPW from ERA5 reanalysis at any lat/lon, allowing full customization (SSP, UHI, events, smoke) and takes ~10 seconds. get_station_epw fetches a published TMYx file from a named station in ~1 second, with no customization — ideal for compliance and reproducibility.

What are the plan requirements for Epwforge?

TMYx/AMY basis generation, UHI, events, and smoke are available on the Starter plan. SSP future‑climate morphing, per‑model ensembles, and compare_scenarios (if it triggers generation) require the Pro plan. find_station, get_station_epw, analyze_epw, and chart tools are free with an API key.

How do compound events work?

When you specify multiple events (e.g., "heatwave,hothumid"), hothumid’s humidity is automatically blended onto the heatwave at 50%. Cold‑family events similarly combine wind onto a cold snap. The primary event intensity slider controls the shape; the secondary is folded into the primary stitch.

What environment variables are required?

EPWFORGE_API_KEY is required — generate one at epwforge.com/account. EPWFORGE_BASE_URL can be set to override the API host (default https://epwforge.com).

Is there a limit on file size?

The server recommends using the save_to parameter to write files to disk instead of returning base64‑encoded content (≈250 KB for a typical year), keeping agent context lean. Tier enforcement returns a 403 if a feature requires a