Epwforge
About
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
Details
- Author
- guzz-labs
- Downloads
- 334
- Categories
- Other
Jump to
- 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.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
EpwforgeCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
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.
find_station
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)
analyze_weather
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.
chart_weather
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_weather_file
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.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"epwforge": {
"epwforge": {
"command": "uvx",
"args": [
"epwforge-mcp@0.3.1"
],
"env": {
"EPWFORGE_API_KEY": "<YOUR_API_KEY_OPTIONAL>"
}
}
}
}
}McpServers
{
"epwforge": {
"command": "uvx",
"args": [
"epwforge-mcp@0.3.1"
],
"env": {
"EPWFORGE_API_KEY": "<YOUR_API_KEY_OPTIONAL>"
}
}
}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.1.6 (Python). Ten tools — single + batch generation, station fetch, analysis, sensitivity sweep, SVG charts. Production backend, Pro-tier features wired in. Mirrored 1:1 by the hosted MCP at https://epwforge.com/api/mcp (so Claude Web users get the same surface).
What is EPWForge?
EPWForge generates and morphs weather files (.epw, .ddy) 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 for any global lat/lon
- AMY (Actual Meteorological Year) — historical hourly weather for hindcasting and calibration
- CMIP6 climate morphing — apply future-scenario deltas (SSP1-2.6, SSP2-4.5, SSP3-7.0) at 7 warming percentiles. SSP5-8.5 was deprecated per CMIP7 (deemed implausible) — use SSP3-7.0 as the high-end scenario.
- Urban Heat Island adjustment — Stewart & Oke LCZ presets (suburban / urban / dense_urban)
- Extreme event injection — heat waves, cold snaps, humidity events, wind events, with auto-compound blending and per-event intensity (1-10 slider, AR6-auto-fill under SSP)
- Wildfire smoke overlays — CAMS-derived AOD with Beer-Lambert solar attenuation, RH bump, temp shift
- Per-model CMIP6 ensembles — up to 21 morphed EPWs (one per model) for inter-model uncertainty analysis
Tools
Nine MCP tools — generation, station discovery + fetch, analysis, sensitivity sweep, and inline SVG charts:
| Tool | Purpose |
|---|---|
| generate_weather_file | Synthesize an EPW from ERA5 reanalysis at any global lat/lon. Combine basis + SSP + UHI + extreme events + smoke in one call. Default vintage 2011-2025 (recent 15 yr); pick another via tmy_period. |
| generate_design_day | DDY file for EnergyPlus design-day sizing, computed from the same enriched hourly data. |
| generate_ensemble | Per-model CMIP6 ensemble — one morphed EPW per climate model (Pro plan). |
| generate_batch | Generate up to 10 EPWs in parallel into a save_to_dir. Same param shape as generate_weather_file per config. Use for parametric sweeps when you want the actual files (not just deltas — that's compare_scenarios). |
| find_station | Search the GuzzStations / OneBuilding library for the nearest published TMYx stations. Returns each station's files[] URLs plus agent_guidance so the LLM asks the user "published station or synthesize?" before generating. |
| get_station_epw | Fetch a published OneBuilding/GuzzStation TMYx file by URL (URL comes from find_station). Returns the .epw (and .ddy when available). |
| analyze_epw | Download an EPW URL and summarize design conditions, degree-days, GHI, monthly temperature shape. No new generation. |
| compare_scenarios | Sensitivity sweep — up to 10 scenarios in parallel, returns only design-condition deltas vs baseline (no full EPW content). |
| chart_diurnal_profile | Inline SVG: monthly Max/Avg/Min hourly profile in °F. Highlights January + July with annual mean overlaid. |
| chart_compare_scenarios | Inline SVG: horizontal bar chart of cooling/heating/dewpoint deltas. Consumes compare_scenarios's response shape directly. |
Most agents will use find_station to discover what's available, then either get_station_epw (for a published TMY) or generate_weather_file (for a custom synthesized one). Reach for analyze_epw / compare_scenarios for quick reads, and chart_* to visualize.
Synthesized vs published — what's the difference?
| | generate_weather_file | get_station_epw |
|---|---|---|
| Source | ERA5 reanalysis at the exact lat/lon | Published TMYx for a named airport / WMO station |
| Speed | ~10s per call | ~1s (cached on the GuzzStations VPS mirror) |
| Customization | Full SSP / UHI / events / smoke / vintage stack | None — file is what it is |
| When to use | Custom site, microclimate concerns, future climate, what-if scenarios | Compliance / submittals, reproducibility, comparison to industry baseline |
| Vintage default | 2011-2025 (configurable via tmy_period) | Whatever the published file is — usually TMYx 2007-2021 |
Quick example
```python
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
