io.github.guzz-labs/epwforge-mcp

Official5 tools

by guzz-labs · Python

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

Generate and process weather files with TMY/AMY morphing and climate data modeling.

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.

Parameters (10)

querystring
Search by city / state (case-insensitive partial match)
latnumber
Latitude — when set, results sorted by proximity
lonnumber
countrystring
ISO 3-letter country code filter, e.g. 'USA', 'GBR'
max_resultsinteger
Max stations (default: 10)
include_amy_extremesboolean
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_deltasboolean
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.
sspstring
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.
yearinteger
Future horizon (only used with include_climate_deltas)
percentileinteger
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.

Parameters (8)

urlstring
EPW URL to analyze (single file)
urlsarray
Multiple EPW URLs for comparison (first = baseline). Max 10.
configobject
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.
compactboolean
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_ashraeboolean
Add ASHRAE 0.4%/1%/2% cooling DB + 99.6%/99% heating DB design conditions to the response. Free. Ignored when compact=true.
include_improbabilityboolean
Add EPWForge's stress-test improbability score (config mode only). Indicates how extreme the synthesized scenario is vs historical baselines.
include_idfboolean
Add ready-to-paste EnergyPlus SizingPeriod:DesignDay IDF objects to the response. AEC-facing. Ignored when compact=true.
unitsstring
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.**

Parameters (10)

urlstring
EPW URL (single-EPW charts: diurnal, temp_carpet, wind_rose, monthly_boxplot, utci_carpet, economizer_carpet, pv_tilt_azimuth)
urlsarray
EPW URLs for chart_type=comparison (first = baseline)
configobject
Synthesize an EPW and chart it. Same params as generate_weather_file. SVG only — no file delivery.
chart_typestring
Default: diurnal
resolutionstring
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_modestring
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_fnumber
economizer_carpet only. ASHRAE 90.1 high-limit shutoff. Defaults: 75°F (drybulb mode) or 28 BTU/lb (enthalpy mode).
econ_supply_air_fnumber
economizer_carpet only. Supply-air temperature setpoint (°F). Default 55.
pv_tiltnumber
pv_tilt_azimuth only. Optional — marks the user's planned tilt (deg, 0=horizontal) on the heatmap alongside the optimum.
pv_azimuthnumber
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.

Parameters (7)

latnumberrequired
Latitude, decimal degrees
lonnumberrequired
Longitude, decimal degrees
sspstring
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.
yearinteger
Future horizon. Pair with ssp.
percentileinteger
Warming percentile. P75 design-realistic; P50 median.
uhistring
Urban Heat Island preset
allow_custom_locationboolean
Required when no OneBuilding station within 50 km

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.

Parameters (21)

latnumberrequired
Latitude, decimal degrees
lonnumberrequired
Longitude, decimal degrees
basisstring
Weather file basis (default: tmy)
amy_yearinteger
Year for AMY basis
sspstring
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.
yearinteger
Future horizon
percentileinteger
Warming percentile (default: 50)
uhistring
Urban Heat Island preset
eventsstring
Comma-separated events. Valid: heatwave, coldsnap, hothumid, coldwindy. Pairs auto-compound (heat+humid, cold+wind).
event_durationinteger
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.
intensitystring
Per-event "type:1-7" intensity (1-10 with stress_test=true). 5 = typical extreme, 7 = severe ~50-yr return.
intensity_autoboolean
Auto-fill unspecified intensities from IPCC AR6 (default: true)
smokeboolean
Enable wildfire smoke overlay
smoke_intensityinteger
Smoke severity 1-10 → peak AOD 0.1-6.0
smoke_durationinteger
Smoke days (3-30, default: 7)
tmy_periodstring
TMYx vintage. Default 2011-2025.
formatstring
Output format (default: epw)
ensembleboolean
Generate a per-model CMIP6 ensemble (~20 EPWs, one per climate model). Costs 10 credits. Requires ssp + year.
scenariosarray
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_testboolean
Unlock intensity 8-10. Default false.
include_ddyboolean
When format=epw, also include the matching DDY in the response (single-file only).

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

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.

claude_desktop_config.json

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

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