# Weather MCP Server

A complete, clean, and modular Model Context Protocol (MCP) server for fetching weather data, forecasts, air quality, and alerts. This server is built using Python and uses the OpenWeatherMap API.

## Features

- **Current Weather:** Get real-time weather conditions for any location.
- **Forecasts:** Access multi-day (up to 5 days) and hourly weather forecasts.
- **Air Quality:** Retrieve Air Quality Index (AQI) and detailed pollutant data.
- **Alerts:** Check for severe weather alerts (requires OpenWeatherMap OneCall 3.0 API subscription).

## Project Structure

```
weather-mcp-server/
├── server.py              # Main MCP server entry point
├── tools/                 # Tool implementations (weather, forecast, air_quality, alerts)
├── services/              # API and business logic (geocoding, openweathermap endpoints)
├── utils/                 # Utilities and constants
├── requirements.txt       # Project dependencies
├── .env.example           # Example environment variables
└── README.md              # Project documentation
```

## Setup & Installation

### 1. Install Dependencies

It is recommended to use a virtual environment.

```bash
cd weather-mcp-server
python -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
pip install -r requirements.txt
```

### 2. Configure Environment Variables

Get a free API key from [OpenWeatherMap](https://openweathermap.org/api).

Copy the example environment file:
```bash
cp .env.example .env
```

Edit `.env` and replace `your_api_key_here` with your actual OpenWeatherMap API key.

## Running the Server

### Development Mode (Testing)

You can run the server directly or use the MCP CLI to inspect it:

```bash
# Optional: Install mcp cli if you want to use the inspector
npm install -g @modelcontextprotocol/inspector

# Run with inspector
npx @modelcontextprotocol/inspector python server.py
```

## Connecting to Claude Desktop

To connect this server to Claude Desktop, you need to configure Claude's `mcp.json` config file.

1. Locate your Claude Desktop configuration file:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add the following to your `mcpServers` configuration (adjust the absolute path to your project):

```json
{
  "mcpServers": {
    "weather": {
      "command": "/absolute/path/to/your/venv/bin/python",
      "args": [
        "/absolute/path/to/weather-mcp-server/server.py"
      ],
      "env": {
        "OPENWEATHER_API_KEY": "YOUR_ACTUAL_API_KEY_HERE"
      }
    }
  }
}
```

3. Restart Claude Desktop. The new weather tools should now be available for Claude to use!

## Tools Provided

- `get_current_weather(location, units)`
- `get_weather_forecast(location, days, units)`
- `get_hourly_forecast(location, hours, units)`
- `get_air_quality(location)`
- `get_weather_alerts(location)`