# 🌦️ Weather MCP Server for Claude Integration

> A production-ready **Model Context Protocol (MCP)** server built using the **official Python MCP SDK** that provides real-time weather information, forecasts, air quality, and weather alerts through the OpenWeatherMap API.

![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)
![OpenWeather](https://img.shields.io/badge/OpenWeather-API-orange.svg)
![License](https://img.shields.io/badge/License-MIT-blue.svg)

---

# 📖 Overview

This project demonstrates how to build a **local MCP Server** using the official **Python MCP SDK**. The server exposes multiple weather-related tools that can be consumed by any MCP-compatible client such as **Claude Code**, **MCP Inspector**, or other MCP hosts.

The server communicates with the OpenWeatherMap API and returns structured weather information through the MCP protocol.

---

# ✨ Features

- 🌤️ Current Weather
- 📅 5-Day Weather Forecast
- 🌪️ Weather Alerts
- 🌫️ Air Quality Index
- 📚 MCP Resources
- 💬 MCP Prompt Templates
- 📝 Structured Logging
- ⚠️ Robust Error Handling
- 🔌 Standard I/O (STDIO) Transport
- 🏗️ Clean Layered Architecture

---

# 🏗️ Architecture

```
                   User
                     │
                     ▼
              Claude Desktop
              Claude Code
             MCP Inspector
                     │
                     ▼
            MCP Protocol (STDIO)
                     │
                     ▼
            Weather MCP Server
                     │
      ┌──────────────┼──────────────┐
      ▼              ▼              ▼
   Tools         Resources      Prompts
      │
      ▼
 OpenWeatherMap REST API
      │
      ▼
 Weather Information
```

---

# 📂 Project Structure

```text
weather-mcp/
│
├── server.py
├── config.py
├── requirements.txt
├── README.md
├── .env.example
│
├── models/
│   ├── weather_model.py
│   └── forecast_model.py
│
├── services/
│   ├── parser.py
│   └── weather_api.py
│
├── tools/
│   ├── current_weather.py
│   ├── forecast.py
│   ├── alerts.py
│   └── air_quality.py
│
├── prompts/
│   └── README.md
│
├── resources/
│   └── README.md
│
├── tests/
│   └── test_weather_parsing.py
│
└── utils/
    ├── logger.py
    ├── helpers.py
    └── exceptions.py
```

---

# ⚙️ Installation

Clone the repository

```bash
git clone https://github.com/PrasadMankar1309/Weather-MCP-Tool-for-the-Claude-Integration.git

cd Weather-MCP-Tool-for-the-Claude-Integration
```

Create a virtual environment

```bash
python -m venv .venv
```

Activate it

### Windows

```bash
.venv\Scripts\activate
```

### Linux / macOS

```bash
source .venv/bin/activate
```

Install dependencies

```bash
pip install -r requirements.txt
```

---

# 🔑 Configuration

Create a `.env` file in the project root.

```env
OPENWEATHER_API_KEY=your_api_key_here
OPENWEATHER_BASE_URL=https://api.openweathermap.org/data/2.5
REQUEST_TIMEOUT_SECONDS=10
LOG_LEVEL=INFO
```

You can obtain a free API key from:

https://openweathermap.org/api

---

# ▶️ Running the MCP Server

```bash
python server.py
```

The server communicates using the **STDIO transport** and is intended to be launched by an MCP-compatible client.

---

# 🔌 Claude Desktop Integration

Example configuration:

```json
{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": [
        "C:/path/to/server.py"
      ]
    }
  }
}
```

Restart Claude Desktop after updating the configuration.

---

# 🔍 Testing with MCP Inspector

Launch the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector
```

Add a new STDIO server:

Command

```text
python
```

Argument

```text
server.py
```

If configured correctly, the Inspector will display:

- Tools
- Resources
- Prompts

---

# 🛠️ Available MCP Tools

| Tool | Description |
|------|-------------|
| Current Weather | Retrieves current weather for a city |
| Forecast | Retrieves weather forecast |
| Weather Alerts | Displays active weather alerts |
| Air Quality | Retrieves AQI information |

---

# 📚 MCP Resources

| Resource | Description |
|-----------|-------------|
| weather://supported-cities | Supported cities |
| weather://api-docs | API information |
| weather://prompt-examples | Example prompts |

---

# 💬 MCP Prompt Templates

- Travel Weather Report
- Farmer Weather Report
- Weather Summary

---

# 💡 Example Prompts

```
What's the weather in Pune?
```

```
Forecast for Mumbai
```

```
Weather alerts in Delhi
```

```
Air quality in London
```

---

# 🔄 MCP Workflow

```text
User Prompt
      │
      ▼
Claude Desktop / Claude Code
      │
      ▼
MCP Client
      │
      ▼
Weather MCP Server
      │
      ▼
OpenWeatherMap API
      │
      ▼
JSON Response
      │
      ▼
Claude Response
```

---

# ⚠️ Error Handling

The server gracefully handles:

- Invalid city names
- Missing API keys
- Network failures
- Request timeouts
- API errors

---

# 🚀 Future Improvements

- Hourly Forecast
- Weather Maps
- Geolocation Support
- Historical Weather
- Severe Weather Notifications
- Multi-language Support
- Docker Deployment
- Streamable HTTP Transport

---

# 🧪 Technologies Used

- Python 3.10
- Model Context Protocol (MCP)
- Official Python MCP SDK
- OpenWeatherMap API
- Dataclasses
- Logging
- dotenv

---

# 🤝 Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Open a Pull Request

---

# 📜 License

This project is licensed under the MIT License.

---

# 👨‍💻 Author

**Prasad Mankar**

- GitHub: https://github.com/PrasadMankar1309
- LinkedIn: https://www.linkedin.com/in/prasad-mankar/

---

⭐ If you found this project useful, consider giving it a star!