🇪🇺🇫🇮 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