# 🌤️ Weather MCP Server

A fully-featured MCP (Model Context Protocol) server providing real-time and historical weather data for any city worldwide. Powered by the free [Open-Meteo API](https://open-meteo.com/) — **no API key required**.

---

## Features

| Tool | Description |
|------|-------------|
| `weather_current` | Real-time weather conditions (temp, humidity, wind, UV, visibility) |
| `weather_forecast` | Multi-day forecast up to 16 days, with optional hourly breakdown |
| `weather_historical` | Historical daily data going back to 1940 |
| `weather_air_quality` | PM2.5, PM10, ozone, NO₂, CO, and US/EU AQI indices |
| `weather_marine` | Wave heights, periods, and ocean wind forecasts |
| `weather_search_location` | Geocode and disambiguate city names |

---

## Quick Start

### Prerequisites
- Node.js 18+
- npm

### Installation

```bash
git clone <repo-url>
cd weather-mcp-server
npm install
npm run build
```

### Running the Server

**stdio mode** (for Claude Desktop, Claude Code, etc.):
```bash
npm start
```

**HTTP mode** (for remote/web integrations):
```bash
TRANSPORT=http npm start
# Server runs on http://localhost:3000/mcp
# Health check: http://localhost:3000/health
```

---

## Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/weather-mcp-server/dist/index.js"]
    }
  }
}
```

---

## Example Usage

Once connected, Claude can answer questions like:

- *"What's the weather in Tokyo right now?"*
- *"Will it rain in London this weekend?"*
- *"How hot was it in Phoenix in July 2023?"*
- *"What's the air quality in Beijing today?"*
- *"What are the surf conditions in Biarritz this week?"*
- *"Show me a 2-week forecast for Dubai in Fahrenheit"*

---

## Tool Reference

### `weather_current`
```json
{
  "location": "Paris",
  "temperature_unit": "celsius",
  "wind_speed_unit": "kmh"
}
```

### `weather_forecast`
```json
{
  "location": "New York",
  "days": 7,
  "include_hourly": false,
  "temperature_unit": "fahrenheit"
}
```

### `weather_historical`
```json
{
  "location": "Sydney",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}
```

### `weather_air_quality`
```json
{
  "location": "Delhi"
}
```

### `weather_marine`
```json
{
  "location": "Miami",
  "days": 3
}
```

### `weather_search_location`
```json
{
  "query": "Springfield",
  "count": 5
}
```

---

## Project Structure

```
weather-mcp-server/
├── src/
│   ├── index.ts              # Server entry point & transport setup
│   ├── constants.ts          # WMO codes, API URLs, limits
│   ├── types.ts              # TypeScript interfaces
│   ├── schemas/
│   │   └── index.ts          # Zod validation schemas
│   ├── services/
│   │   └── weatherApi.ts     # API client & shared utilities
│   └── tools/
│       ├── currentWeather.ts
│       ├── forecast.ts
│       ├── historical.ts
│       ├── airQuality.ts
│       ├── marine.ts
│       └── geocoding.ts
└── dist/                     # Compiled output (run `npm run build`)
```

---

## Data Sources

All data comes from [Open-Meteo](https://open-meteo.com/):
- **Weather & Forecast**: `api.open-meteo.com`
- **Historical Archive**: `archive-api.open-meteo.com`
- **Air Quality**: `air-quality-api.open-meteo.com`
- **Marine**: `marine-api.open-meteo.com`
- **Geocoding**: `geocoding-api.open-meteo.com`

Free tier supports unlimited non-commercial use.

---

## License

MIT