# 🌦️ Weather MCP Server (Python)

A high-performance Model Context Protocol (MCP) server providing real-time weather observations, hourly forecasts, multi-day daily forecasts, and air quality analysis for any location globally.

Built with Python and the official **Model Context Protocol SDK** (`mcp` / `FastMCP`), powered by the free and keyless **[Open-Meteo API](https://open-meteo.com/)**.

---

## ✨ Features

- 🌍 **Global Geocoding**: Automatically resolves city names, regions, countries, and landmarks to exact coordinates and timezones.
- 🌡️ **Current Weather**: Real-time temperature, apparent ("feels-like") temperature, humidity, precipitation, cloud cover, wind speed & cardinal direction, and pressure.
- 📆 **Daily Forecasts**: Up to 16-day forecasts with daily highs/lows, precipitation probabilities & volume, max UV index, and sunrise/sunset times.
- ⏱️ **Hourly Forecasts**: Granular hour-by-hour forecast tables with rain chances, temperatures, and conditions.
- 🍃 **Air Quality & UV**: Comprehensive US & European AQI, PM2.5, PM10, Ozone, NO₂, SO₂, CO, dust levels, and health recommendations.
- 🔒 **Zero API Keys Required**: Powered by Open-Meteo with no authentication or account needed.
- ⚡ **Async & Non-blocking**: Uses `httpx` for fast, lightweight network requests.

---

## 🛠️ MCP Tools Reference

### 1. `get_current_weather`
Fetch live weather conditions for any location.
- **Parameters**:
  - `location` *(str, required)*: City, region, or landmark (e.g. `"Tokyo"`, `"London"`, `"San Francisco, US"`).
  - `units` *(str, optional)*: Temperature unit — `"celsius"` (default) or `"fahrenheit"`.

### 2. `get_daily_forecast`
Get a multi-day forecast breakdown.
- **Parameters**:
  - `location` *(str, required)*: City or landmark.
  - `days` *(int, optional)*: Number of forecast days from 1 to 16 (default: `5`).
  - `units` *(str, optional)*: `"celsius"` (default) or `"fahrenheit"`.

### 3. `get_hourly_forecast`
Get an hour-by-hour forecast.
- **Parameters**:
  - `location` *(str, required)*: City or landmark.
  - `hours` *(int, optional)*: Number of hours ahead from 1 to 48 (default: `24`).
  - `units` *(str, optional)*: `"celsius"` (default) or `"fahrenheit"`.

### 4. `get_air_quality`
Get current air quality, particulate concentrations, and UV index.
- **Parameters**:
  - `location` *(str, required)*: City or landmark.

---

## 📋 MCP Prompts & Resources

- **Resource**: `weather://{location}/current` — Dynamic resource to read current weather data.
- **Prompt**: `weather_briefing` — Pre-built prompt to generate tailored morning, travel, or outdoor activity advisories.

---

## 🚀 Installation & Setup

### Prerequisites
- Python 3.10+
- [`uv`](https://docs.astral.sh/uv/) (recommended) or `pip`

### 1. Clone or Navigate to Project
```bash
cd C:\Users\Bhargav-Kahar\.gemini\antigravity\scratch\weather-mcp-server
```

### 2. Install Dependencies
Using `uv`:
```bash
uv venv
uv pip install -e .
```
Or using standard `pip`:
```bash
python -m venv .venv
.venv\Scripts\activate
pip install -e .
```

### 3. Run Verification Tests
```bash
.venv\Scripts\python test_server.py
```

---

## 🔌 MCP Client Configuration

### Claude Desktop Configuration
Add the server to your Claude Desktop config file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "weather": {
      "command": "C:\\Users\\Bhargav-Kahar\\.gemini\\antigravity\\scratch\\weather-mcp-server\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\Bhargav-Kahar\\.gemini\\antigravity\\scratch\\weather-mcp-server\\weather_server.py"
      ]
    }
  }
}
```

*Or using `uv` directly:*
```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\Bhargav-Kahar\\.gemini\\antigravity\\scratch\\weather-mcp-server",
        "run",
        "weather_server.py"
      ]
    }
  }
}
```

### Antigravity / Gemini MCP Configuration
In your workspace `.agents/mcp_config.json` or `~/.gemini/config/mcp_config.json`:
```json
{
  "mcpServers": {
    "weather": {
      "command": "C:\\Users\\Bhargav-Kahar\\.gemini\\antigravity\\scratch\\weather-mcp-server\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\Bhargav-Kahar\\.gemini\\antigravity\\scratch\\weather-mcp-server\\weather_server.py"
      ]
    }
  }
}
```

---

## 📂 Project Structure

```
weather-mcp-server/
├── pyproject.toml         # Package metadata and dependencies
├── weather_server.py      # Main MCP server implementation
├── test_server.py         # Automated verification test suite
└── README.md              # Documentation and client setup guide
```

---

## 📄 License
MIT License