# ⛅ Weather MCP Server

A lightweight MCP (Model Context Protocol) server that exposes a single tool — real-time weather lookup for any location — to any MCP-compatible client, such as Claude Desktop.

---

## 🧠 How It Works

1. A `FastMCP` server named **"Weather Checker"** is started over **stdio transport**.
2. It exposes one async tool, `check_weather(location: str)`, callable by any connected MCP client.
3. Internally, the tool calls `get_weather()`, which hits [wttr.in](https://wttr.in) — a free, no-auth-required weather service — and returns a concise, one-line weather summary for the given location.
4. No API keys, no sign-ups, no external dependencies beyond the `mcp` package itself.

---

## 🗂️ Project Structure

```
├── main.py                 # MCP server entry point — defines and runs the check_weather tool
├── tools/
│   ├── __init__.py
│   └── weather.py          # Fetches weather data from wttr.in
├── pyproject.toml          # Project metadata and dependencies (uv-managed)
├── requrements.txt          # Pip-installable dependencies
├── uv.lock                  # Locked dependency versions
└── .python-version          # Python 3.13
```

---

## 🛠️ Tech Stack

| Layer | Technology |
|---|---|
| **Protocol** | MCP (Model Context Protocol) — `FastMCP`, stdio transport |
| **Weather Data Source** | [wttr.in](https://wttr.in) — free console-friendly weather API |
| **HTTP Client** | Python standard library (`urllib.request`) |
| **Package Management** | uv |
| **Language** | Python 3.13 |

---

## ⚙️ Local Setup

### 1. Clone the Repository
```bash
git clone https://github.com/<your-username>/<repo-name>.git
cd <repo-name>
```

### 2. Install Dependencies

Using `uv` (recommended, matches `uv.lock`):
```bash
uv sync
```

Or using standard `venv` + pip:
```bash
python -m venv .venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate
pip install -e .
```

### 3. Run the Server
```bash
python main.py
```
The server starts and communicates over **stdio** — it's designed to be launched by an MCP client, not accessed directly via a browser or REST call.

---

## 🔌 Connecting to an MCP Client

To use this server with an MCP-compatible client (e.g. Claude Desktop), add it to the client's MCP server configuration:

```json
{
  "mcpServers": {
    "weather-checker": {
      "command": "python",
      "args": ["main.py"]
    }
  }
}
```

If using `uv`:
```json
{
  "mcpServers": {
    "weather-checker": {
      "command": "uv",
      "args": ["run", "main.py"]
    }
  }
}
```

Once connected, the client can call the `check_weather` tool directly — for example, asking "What's the weather in London?" will invoke `check_weather(location="London")` behind the scenes.

---

## 🔧 Available Tools

| Tool | Parameters | Returns | Description |
|---|---|---|---|
| `check_weather` | `location: str` (e.g. `"New York"`, `"London"`) | Concise weather summary (string) | Fetches current weather conditions for the specified location via wttr.in |

### Example Output
```
New York: ☀️   +24°C
```

---

## 📌 Key Features

- ✅ Zero-configuration — no API keys or environment variables required
- ✅ Minimal dependency footprint (`mcp[cli]` only)
- ✅ Clean separation between MCP tool definition (`main.py`) and the underlying data-fetch logic (`tools/weather.py`)
- ✅ Graceful error handling — returns a readable error string instead of raising on failed requests
- ✅ Async tool definition, ready to scale to additional tools in the same server

---

## 📄 License

This project is for educational purposes.