# epwforge-mcp

**Category:** 🌳 Environment & Nature  
**Repository:** https://github.com/guzz-labs/epwforge-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/epwforge-mcp

## Description
EPW & DDY weather files for any location — TMY, CMIP6 SSPs, UHI, extreme events, smoke.

## Tools
Capabilities this server exposes over MCP:

- **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).
- **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`.
- **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`.
- **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).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "epwforge-mcp": {
    "command": "uvx",
    "args": ["epwforge-mcp"],
    "env": {
      "EPWFORGE_API_KEY": "",
      "EPWFORGE_BASE_URL": ""
    }
  }
}
```

**Requires environment variables:** `EPWFORGE_API_KEY`, `EPWFORGE_BASE_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What epwforge-mcp MCP server does

The epwforge-mcp MCP server exposes EPWForge weather-data operations to MCP-compatible AI clients. It supports workflows for EnergyPlus, OpenStudio, IES VE, eQUEST, and other tools that consume weather files. The service can work with published TMYx station data or synthesize weather scenarios for coordinates.

Its source data and scenario features cover TMYx generation from ERA5 reanalysis, historical AMY years from 1950 onward, CMIP6 SSP projections, urban heat-island adjustments, and injected events such as heatwaves, cold snaps, hot-humid conditions, cold-windy conditions, and wildfire smoke. Generated outputs can include EPW, DDY, CSV, ZIP, and PVsyst formats.

## How it works

Four MCP tools provide the interface:

- `find_station` searches the GuzzStations catalog by station name, country, or coordinates. The optional compact response returns only the newest TMYx for each station.
- `analyze_weather` summarizes one EPW, compares two to ten URLs, or calculates statistics for a scenario supplied as coordinates and configuration. Configuration mode returns statistics rather than EPW content.
- `chart_weather` returns inline SVG charts for temperature, wind, solar, UTCI, economizer conditions, monthly distributions, and comparisons. Large charts may be returned through a URL instead.
- `generate_weather_file` creates a downloadable file using the selected morphing options. It also supports bundles and an all-SSP ensemble mode.

Analysis can include ASHRAE design conditions, improbability metrics, and IDF output when requested. Scenario inputs can specify an SSP, year, warming percentile, UHI preset, event type, intensity, duration, and smoke settings.

## Setup and configuration

Install the Python package with `pip install epwforge-mcp`, or run it with `uvx epwforge-mcp`. Python 3.10 or newer is required. A local MCP client can start the `epwforge-mcp` command and optionally pass `EPWFORGE_API_KEY` in its environment. `EPWFORGE_BASE_URL` can replace the default API host, primarily for testing against another backend.

`find_station`, `analyze_weather`, and `chart_weather` work without authentication. `generate_weather_file` requires an API key and available credits. The hosted equivalent is available at `https://epwforge.com/api/mcp` for browser-based MCP clients.

## Limitations and notes

The epwforge-mcp MCP server does not return EPW content from station search or analysis operations. Configuration-based analysis also keeps the synthesized file server-side and returns statistics only. Use `generate_weather_file` when the actual downloadable artifact is needed.

Credit usage applies only to generation. A single EPW, DDY, CSV, or PVsyst file costs one credit; bundles and all-SSP generation can cost two credits, while CMIP6 ensemble generation is charged per model at ten credits. Calls made without sufficient credits return an HTTP 402 surfaced as an MCP `ToolError` with a hint.

The server uses consolidated tools. Older operations such as design-day generation, ensemble generation, EPW analysis, and scenario comparison are now reached through parameters on the four current tools. Exact parameters and behavior are documented at EPWForge’s documentation site, in the package tool docstrings, and through the running server’s `tools/list` response.

_Full upstream README: https://allmcps.com/mcp/epwforge-mcp/readme_