🇪🇺🇫🇮 mcp-weather

A Model Context Protocol (MCP) server that aggregates weather data from 6 sources, optimized for European and Nordic/Baltic locations. Works out of the box with zero API keys -- add optional keys to unlock more sources.

Features

6 weather sources -- Open-Meteo, wttr.in, METAR, OpenWeatherMap, WeatherAPI, Tomorrow.io
6 MCP tools -- current weather, forecast, air quality, aviation METAR, astronomy, source status
Nordic/Finnish focus -- 30+ Finnish cities with instant alias resolution (e.g. hki, tre, stadi), Nordic/Baltic capitals included
Multi-source aggregation -- merges data from all available sources for more complete and accurate results
Zero-config start -- 3 sources work without any API keys (Open-Meteo, wttr.in, METAR)
Smart caching -- LRU cache with stampede prevention, configurable TTL

MCP Tools

Tool	Description
`get_current_weather`	Current conditions from up to 5 sources, merged into one result
`get_weather_forecast`	1-7 day daily forecast (temperature, precipitation, wind, UV)
`get_air_quality`	European AQI with PM2.5, PM10, NO2, O3, SO2, CO levels
`get_metar`	Aviation weather (raw + decoded) from aviationweather.gov
`get_astronomy`	Sunrise, sunset, day length, moon phase and illumination
`get_weather_source_status`	Health check for all sources + cache statistics

Location Input

The server accepts multiple location formats:

Format	Example	Notes
Finnish alias	`hki`, `tre`, `stadi`, `turku`	30+ cities with ICAO codes
Nordic capital	`stockholm`, `oslo`, `tallinn`	Finnish names work too (`tukholma`)
City name	`London`, `Berlin`, `Tokyo`	Geocoded via Open-Meteo
Coordinates	`60.17,24.94`	Latitude, longitude
ICAO code	`EFHK`, `ESSA`	For METAR tool

Quick Start

Docker (recommended)

git clone https://github.com/Koneisto/mcp-weather.git
cd mcp-weather
cp .env.example .env          # optionally add API keys
npm install && npm run build  # build TypeScript
docker compose up -d

The server will be available at http://localhost:3015 via supergateway (Streamable HTTP transport).

Local Development

git clone https://github.com/Koneisto/mcp-weather.git
cd mcp-weather
npm install
npm run build
node build/index.js           # runs on stdio transport

Claude Desktop / Claude Code

Add to your MCP client configuration:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/mcp-weather/build/index.js"],
      "env": {
        "OPENWEATHERMAP_API_KEY": "",
        "WEATHERAPI_KEY": "",
        "TOMORROW_IO_API_KEY": ""
      }
    }
  }
}

Configuration

All settings are via environment variables. Copy .env.example to .env to get started.

Variable	Default	Description
`OPENWEATHERMAP_API_KEY`	(empty)	OpenWeatherMap free tier key
`WEATHERAPI_KEY`	(empty)	WeatherAPI free tier key
`TOMORROW_IO_API_KEY`	(empty)	Tomorrow.io free tier key
`CACHE_TTL_MINUTES`	`60`	Cache time-to-live in minutes
`CACHE_MAX_ENTRIES`	`200`	Maximum cached responses
`HTTP_TIMEOUT_MS`	`10000`	HTTP request timeout in milliseconds

Sources by API Key Requirement

Source	Requires Key	Data Provided
Open-Meteo	No	Current, forecast, air quality
wttr.in	No	Current conditions
METAR	No	Aviation weather
OpenWeatherMap	Yes	Current conditions
WeatherAPI	Yes	Current conditions, astronomy (moon)
Tomorrow.io	Yes	Current conditions, air quality

Architecture

src/
  index.ts              # MCP server entry point (stdio transport)
  config.ts             # Environment variable loading
  cache.ts              # LRU cache with stampede prevention
  types.ts              # Shared TypeScript interfaces
  tools/
    current-weather.ts  # get_current_weather
    forecast.ts         # get_weather_forecast
    air-quality.ts      # get_air_quality
    metar.ts            # get_metar
    astronomy.ts        # get_astronomy
    source-status.ts    # get_weather_source_status
  sources/
    open-meteo.ts       # Open-Meteo (current, forecast, AQI)
    wttr-in.ts          # wttr.in (current)
    openweathermap.ts   # OpenWeatherMap (current)
    weatherapi.ts       # WeatherAPI (current, astronomy)
    tomorrow-io.ts      # Tomorrow.io (current, AQI)
    metar.ts            # aviationweather.gov (METAR)
  utils/
    aggregator.ts       # Multi-source data merging
    finnish-locations.ts # Finnish/Nordic city alias map
    location.ts         # Location resolution (alias -> geocode -> coords)
    units.ts            # Unit conversions and WMO weather codes

Transport

The server uses stdio transport natively. The Docker setup wraps it with supergateway to expose it as a Streamable HTTP endpoint on port 3000 (mapped to 3015 in docker-compose).

License

MIT

mcp-weather