# Weather MCP Server

An [MCP](https://modelcontextprotocol.io/) server that exposes US weather data from the [National Weather Service (NWS) API](https://www.weather.gov/documentation/services-web-api). Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk) and `httpx`.

## Requirements

- Python 3.13+
- [uv](https://docs.astral.sh/uv/) (recommended) or another package manager

## Setup

```bash
uv sync
```

Or with pip:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Run the server

The server uses **stdio** transport (standard for local MCP clients):

```bash
uv run weather.py
```

Or:

```bash
python weather.py
```

## Tools

| Tool | Arguments | Description |
|------|-----------|-------------|
| `get_alerts` | `state` (two-letter US state code, e.g. `CA`, `NY`) | Active weather alerts for that state |
| `get_forecast` | `latitude`, `longitude` | Forecast for the next 5 periods at that location |

Both tools call `https://api.weather.gov` and return human-readable text.

## Use with Cursor / Claude Desktop

Add the server to your MCP client config. Example for Claude Desktop / Cursor:

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

Replace `/absolute/path/to/weather` with this project’s path. You can also point `command` at your Python interpreter and pass `weather.py` as the only arg.

## Testing

Call the tools directly (no MCP client):

```bash
python test_direct.py
```

Other scripts in the repo exercise MCP stdio / JSON-RPC flows (`test_mcp.py`, `test_mcp_simple.py`, `test_mcp_proper.py`, `test_mcp_integration.py`, `test_direct_io.py`).

## Project layout

```
weather.py   # FastMCP server and NWS tools
main.py      # Placeholder entrypoint
pyproject.toml
```

## Notes

- Data is US-only (NWS coverage).
- Logs go to **stderr** so they do not interfere with stdio MCP messages.
- Forecasts are limited to the next 5 forecast periods.