# 🇪🇺🇫🇮 mcp-weather
A [Model Context Protocol](https://modelcontextprotocol.io/) (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)
```bash
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](https://github.com/nichochar/supergateway) (Streamable HTTP transport).
### Local Development
```bash
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:
```json
{
"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](https://openweathermap.org/api) free tier key |
| `WEATHERAPI_KEY` | *(empty)* | [WeatherAPI](https://www.weatherapi.com/) free tier key |
| `TOMORROW_IO_API_KEY` | *(empty)* | [Tomorrow.io](https://www.tomorrow.io/weather-api/) 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](https://github.com/nichochar/supergateway) to expose it as a **Streamable HTTP** endpoint on port 3000 (mapped to 3015 in docker-compose).
## License
[MIT](LICENSE)
