# Weather MCP Server (OpenWeather API)

A Model Context Protocol (MCP) server built with Python and [`uv`](https://github.com/astral-sh/uv) that provides weather information by city name using the OpenWeather API (`https://api.openweathermap.org/data/2.5/weather`).

---

## Table of Contents

- [Features](#features)
- [Prerequisites](#prerequisites)
- [Step-by-Step Setup Guide](#step-by-step-setup-guide)
  - [Step 1: Clone / Navigate to Project Directory](#step-1-clone--navigate-to-project-directory)
  - [Step 2: Environment Configuration](#step-2-environment-configuration)
  - [Step 3: Install Dependencies](#step-3-install-dependencies)
  - [Step 4: Run the MCP Server](#step-4-run-the-mcp-server)
  - [Step 5: Test Interactively with MCP Inspector](#step-5-test-interactively-with-mcp-inspector)
  - [Step 6: Run Automated Tests](#step-6-run-automated-tests)
- [MCP Tools Reference](#mcp-tools-reference)
- [MCP Client Integration](#mcp-client-integration)
- [Project Structure](#project-structure)

---

## Features

- **Get Weather by City Name**: Fetches real-time weather metrics for any city (e.g., `London`, `Chennai`, `New York,US`).
- **Structured JSON Output**: Returns temperature (°C), feels-like (°C), humidity (%), pressure (hPa), weather conditions, and wind speed (m/s).
- **Environment Key Integration**: Loads `OPENWEATHER_API_KEY` automatically via `.env` / `dotenv`.
- **Package Management via `uv`**: Uses `pyproject.toml` and `uv` for reproducible builds.

---

## Prerequisites

- **Python**: `>= 3.10`
- **`uv`**: Fast Python package manager ([Installation Guide](https://docs.astral.sh/uv/getting-started/installation/))
- **Node.js & npx** (Optional, for testing with MCP Inspector)
- **OpenWeather API Key**: Free key from [OpenWeather SignUp](https://home.openweathermap.org/users/sign_up)

---

## Step-by-Step Setup Guide

## VS Code Configuration

### Step 1: Clone / Navigate to Project Directory

```bash
cd /Users/jayarajkannan/Learnings/project/mcp
```

### Step 2: Environment Configuration

Create a `.env` file from `.env.example` and set your OpenWeather API key:

```bash
cp .env.example .env
```

Edit `.env`:
```env
OPENWEATHER_API_KEY=your_actual_openweather_api_key_here
```

### Step 3: Install Dependencies

Sync virtual environment and lockfile using `uv`:

```bash
uv sync
```

This installs `mcp`, `httpx`, and `python-dotenv` into the project environment.

---

### Step 4: Run the MCP Server

You can run the server directly using `uv`:

```bash
uv run server.py
```

Or using the CLI script entry point defined in `pyproject.toml`:

```bash
uv run weather-mcp
```

> **Note**: MCP servers communicate over `stdio` via JSON-RPC. Running the script directly will wait for input on stdin.

---

### Step 5: Test Interactively with MCP Inspector

Use the official MCP Inspector to test and verify all tool calls in your browser UI:

```bash
npx @modelcontextprotocol/inspector uv run server.py
```

1. Open the URL printed in the terminal (e.g. `http://127.0.0.1:6274?...`).
2. Click **Connect**.
3. Select the `get_weather` tool.
4. Input a city name (e.g. `London` or `Chennai`) and click **Run Tool**.

---

### Step 6: Run Automated Tests

Run the test suite using `unittest` and `uv`:

```bash
uv run python -m unittest test_server.py
```

---

## MCP Tools Reference

### `get_weather`

Gets current weather for a city using OpenWeather API.

#### Input Schema

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `city` | `string` | **Yes** | City name (e.g. `"London"`, `"Chennai"`, `"New York"`) |

#### Example Response Output

```json
{
  "city": "London",
  "country": "GB",
  "temperature_c": 21.57,
  "feels_like_c": 21.58,
  "humidity": 69,
  "pressure": 1006,
  "weather": "Clouds",
  "description": "broken clouds",
  "wind_speed_mps": 9.26
}
```

---

## MCP Client Integration

Add the Weather MCP server to your MCP client configuration (e.g. Claude Desktop `claude_desktop_config.json` or Antigravity `.mcp.json`):
## For VS code configuration
  `ctrl+shift+p`  for windows , `cmd+shift+p` mac

search ` >mcp: open user configuration `

it will open a `mcp.json`  file update the below config there

```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/jayarajkannan/Learnings/project/mcp",
        "run",
        "server.py"
      ],
      "env": {
        "OPENWEATHER_API_KEY": "YOUR_OPENWEATHER_API_KEY"
      }
    }
  }
}
```

---

## Project Structure

```text
├── pyproject.toml    # Project dependencies and script entry points
├── uv.lock           # Locked dependency tree
├── server.py         # Weather MCP server implementation
├── test_server.py    # Automated unit tests
├── .env.example      # Sample environment configuration
├── .env              # Local environment variables (API Key)
└── README.md         # Documentation
```