open-meteo-mcp-server

<div align="center">
  <h1>@cyanheads/open-meteo-mcp-server</h1>
  <p><b>Geocode places, fetch global weather forecasts, historical climate, marine conditions, air quality, and terrain elevation via MCP. STDIO or Streamable HTTP.</b>
  <div>12 Tools</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.4.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/open-meteo-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/open-meteo-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/open-meteo-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/open-meteo-mcp-server/releases/latest/download/open-meteo-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=open-meteo-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvb3Blbi1tZXRlby1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22open-meteo-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fopen-meteo-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://open-meteo.caseyjhand.com/mcp](https://open-meteo.caseyjhand.com/mcp)

</div>

---

## Overview

Global weather from Open-Meteo: forecasts, the historical archive, marine conditions, air quality, probabilistic ensembles, river discharge, and CMIP6 climate projections. Geocode a place name, pull hourly and daily variables for its coordinates, and run SQL over large results staged to DataCanvas. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

### Tools

| Tool | Description |
|:---|:---|
| `openmeteo_search_locations` | Resolve a place name to ranked coordinates with country, region, timezone, and population |
| `openmeteo_get_forecast` | Current conditions and hourly/daily forecast up to 16 days, with up to 92 past days |
| `openmeteo_get_historical` | Hourly/daily history from the reanalysis archive, 1940 to present |
| `openmeteo_get_marine` | Wave, swell, and sea-surface conditions: up to 8 forecast days or an archive range |
| `openmeteo_get_air_quality` | Modeled CAMS pollutants, pollen, and AQI: current, up to 7 forecast days, or an archive range |
| `openmeteo_get_elevation` | Copernicus DEM terrain elevation for up to 100 coordinate pairs |
| `openmeteo_get_ensemble` | Per-member ensemble forecast (up to 64 members, up to 35 days) for exceedance and uncertainty |
| `openmeteo_get_flood` | GloFAS river discharge forecast (up to 210 days) or reanalysis from 1984 |
| `openmeteo_get_climate` | Bias-corrected daily CMIP6 projections, 1950–2050, across up to 7 models |
| `openmeteo_dataframe_describe` | List the tables and columns staged on a DataCanvas |
| `openmeteo_dataframe_query` | Run a read-only SQL `SELECT` against staged tables |
| `openmeteo_dataframe_drop` | Remove one staged table or view from a DataCanvas (opt-in) |

## Capability reference

### `openmeteo_search_locations` <sub>tool</sub>

- A bare place `name` ("Paris", not "Paris, France"), with optional `country` (ISO 3166-1 alpha-2) and `language` (default `en`); `count` 1–10, default 5
- Each result carries coordinates, an IANA `timezone`, `country` / `country_code`, `admin1` / `admin2`, `population`, and `feature_code`; no match fails as `no_results`
- A `notice` flags a top match with null or sub-100,000 population, which is what a historic exonym ("Bangalore", "Calcutta") often resolves to
- A native-script query that misses under `en` is retried once in the language its script implies; when that retry finds the results, `effective_language` names it (`上海` → `zh`), since their `name`, `country`, `admin1`, and `admin2` come back localized in it

---

### `openmeteo_get_forecast` <sub>tool</sub>

- At least one of `current_variables`, `hourly_variables`, or `daily_variables` (up to 50 each); `forecast_days` 1–16 (default 7), `past_days` 0–92 (default 0)
- Per-timestamp `hourly` / `daily` records with `hourly_units` / `daily_units`; `current_variables` adds a `current` object from 15-minute data (`interval` 900) plus `current_units`
- Prefer `past_days` over `openmeteo_get_historical` for the last ~5 days, where the archive's ERA5 components lag

---

### `openmeteo_get_historical` <sub>tool</sub>

- `start_date` and `end_date` required (YYYY-MM-DD, from 1940-01-01), plus at least one of `hourly_variables` / `daily_variables`, named as on the forecast tool
- Omitting `models` reads Best Match (IFS HRES + ERA5 + ERA5-Land, source varies by date); up to 8 `models` pin a source. The ERA5 family runs ~5 days behind, `ecmwf_ifs` has no delay, and `cerra` covers Europe only
- Output echoes `models` and the returned `date_range`; with 2+ models each column carries a model-name suffix

---

### `openmeteo_get_marine` <sub>tool</sub>

- One window per call: `forecast_days` 1–8 (upstream default 7) with `past_days` 0–92, or a `start_date` / `end_date` archive range back to at least 2022. Mixing them fails as `forecast_window_conflict`, a lone date as `date_range_incomplete`
- At least one of `hourly_variables` / `daily_variables` (wave height, period, and direction, swell, sea-surface temperature); sheltered water returns near-zero waves, a land point returns nulls (named in the `notice`), and `ocean_current_velocity` is null off the open ocean

---

### `openmeteo_get_air_quality` <sub>tool</sub>

- One window per call: `forecast_days` 1–7 (upstream default 5) with `past_days` 0–92, or a `start_date` / `end_date` archive range from August 2022 (`us_aqi` starts a day later). Same `forecast_window_conflict` and `date_range_incomplete` rejections as the marine tool
- At least one of `current_variables` (a `current` object, `interval` 3600) or `hourly_variables`: PM2.5, PM10, NO2, SO2, O3, CO, dust, pollen, European and US AQI. Pollen is modeled for Europe only, in pollen season; elsewhere it comes back null and the `notice` names it
- `data_source: "CAMS"` marks every response as modeled grid data, not station measurements

---

### `openmeteo_get_elevation` <sub>tool</sub>

- Parallel `latitudes[]` / `longitudes[]` arrays of up to 100 pairs; unequal lengths fail as `coordinate_count_mismatch`
- `elevations[]` in input order, each `{ latitude, longitude, elevation_m }` from the Copernicus DEM (~90 m); `elevation_m` is `null` where the DEM has no value (latitude 90), without failing the rest of the call

---

### `openmeteo_get_ensemble` <sub>tool</sub>

- At least one of `hourly_variables` / `daily_variables`; `forecast_days` 1–35 (default 7), `past_days` 0–92. Most models end within 16 days (`ncep_gefs05` runs to about day 34); past a model's horizon its columns are null and the `notice` names where its data ends. `models` takes one ensemble name (e.g. `ecmwf_ifs025_ensemble`, 51 members; `gem_global_ensemble`, 21); omitted or blank, it selects `ecmwf_ifs025_ensemble`, which the `model` field echoes
- Each variable returns as per-member columns (`temperature_2m_member01`, …) across up to 64 members; `member_count` counts the perturbed members, not the control run
- A regional model queried outside its coverage fails as a non-retryable input error naming the gap; switch to a global model

---

### `openmeteo_get_flood` <sub>tool</sub>

- `daily_variables` required (up to 20), all in m³/s: `river_discharge`, the daily discharge value, and the ensemble statistics `river_discharge_mean` / `_median` / `_min` / `_max` / `_p25` / `_p75`. The statistics exist in forecast mode only; in reanalysis mode they repeat `river_discharge` and carry no spread
- One mode per call: `forecast_days` 1–210, or a `start_date` / `end_date` reanalysis range from 1984-01-01. Mixing them fails as `forecast_days_conflict`, a lone date as `date_range_incomplete`
- Discharge comes from the largest modeled river within 5 km, not always the closest; vary the coordinate by ~0.1° when a value looks off. Null outside GloFAS coverage

---

### `openmeteo_get_climate` <sub>tool</sub>

- `start_date` / `end_date` within 1950-01-01 to 2050-12-31 and `daily_variables` required (the API is daily-only); up to 7 CMIP6 `models`, e.g. `CMCC_CM2_VHR4`, `MRI_AGCM3_2_S`
- With 2+ models each variable is suffixed with the model name; a single or omitted model returns plain names. A variable a model doesn't carry comes back null

---

### `openmeteo_dataframe_describe` <sub>tool</sub>

- Takes the `canvas_id` a spilled weather tool returned; lists each table's `name`, `kind`, `row_count`, and columns (name, type, nullability), plus the canvas `expires_at`
- Fails as `canvas_not_enabled` when canvas is off, or `canvas_not_found` when the ID is unknown or past its 24-hour sliding TTL

---

### `openmeteo_dataframe_query` <sub>tool</sub>

- `canvas_id` plus a read-only `SELECT` against the staged `tab