# Weather MCP Learning

> This repository is an educational project created only to learn more about the Model Context Protocol (MCP). It is not intended to be a production weather service.

MCP is an open protocol that gives AI applications a standard way to connect to external tools and data sources. An MCP server exposes capabilities such as tools, resources, or prompts, while an MCP client—such as Claude Desktop—discovers and uses those capabilities through a defined interface.

This project implements a small Python MCP server that retrieves weather information from the United States National Weather Service (NWS) API.

## Available tools

- `get_alerts(state)`: Returns active weather alerts for a two-letter US state code, such as `CA` or `NY`.
- `get_forecast(latitude, longitude)`: Returns a short forecast for a location in the United States.

The NWS API primarily covers locations in the United States and its territories.

## Requirements

- Python 3.12 or later
- [uv](https://docs.astral.sh/uv/)
- An MCP client, such as Claude Desktop

## Run locally

Clone the repository and start the server with the `stdio` transport:

```bash
git clone https://github.com/hienguyenUET/weather_mcp_learning.git
cd weather_mcp_learning
uv sync
uv run weather.py
```

## Configure Claude Desktop

Add the server to the `mcpServers` object in your Claude Desktop configuration file:

```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/weather_mcp_learning",
        "run",
        "weather.py"
      ]
    }
  }
}
```

Restart Claude Desktop after saving the configuration. Claude should then discover the `get_alerts` and `get_forecast` tools.

## Example prompts

- "Are there any active weather alerts in California?"
- "What is the weather forecast for latitude 34.0522 and longitude -118.2437?"

## Project structure

```text
weather_mcp_learning/
├── weather.py       # MCP server and weather tools
├── pyproject.toml   # Project metadata and dependencies
└── uv.lock          # Locked dependency versions
```

## Data source

Weather data is provided by the public [National Weather Service API](https://www.weather.gov/documentation/services-web-api). No API key is required.