# Weather MCP Server

A Model Context Protocol (MCP) server that provides weather data tools using the National Weather Service (NWS) API.

## Overview

This MCP server exposes two main tools for accessing weather information:

- **get_alerts**: Fetch active weather alerts for a US state
- **get_forecast**: Retrieve detailed weather forecasts for a specific latitude/longitude

The server is built using FastMCP and communicates over stdio transport, making it compatible with MCP clients like Claude Desktop.

## Features

- 🌤️ Real-time weather forecasts from the National Weather Service
- ⚠️ Active weather alerts by state
- 🔄 Async API calls for efficient data retrieval
- 🛡️ Robust error handling and user-friendly responses
- 📦 Easy integration with MCP-compatible clients

## Requirements

- Python 3.11 or higher
- [uv](https://github.com/astral-sh/uv) package manager (recommended)

## Installation

### Using uv (recommended)

```bash
# Clone the repository
git clone <repository-url>
cd weather

# Install dependencies
uv sync

# Activate virtual environment
source .venv/bin/activate
```

### Using pip

```bash
# Clone the repository
git clone <repository-url>
cd weather

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .
```

## Usage

### Running the Server

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

### Integration with MCP Clients

To use this server with an MCP client like Claude Desktop, add it to your MCP configuration:

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

### Available Tools

#### get_alerts

Fetch active weather alerts for a US state.

**Parameters:**
- `state` (string): Two-letter US state code (e.g., "CA", "NY")

**Example:**
```python
get_alerts(state="CA")
```

#### get_forecast

Retrieve weather forecast for a specific location.

**Parameters:**
- `latitude` (float): Latitude coordinate
- `longitude` (float): Longitude coordinate

**Example:**
```python
get_forecast(latitude=37.7749, longitude=-122.4194)
```

## API Integration

This server uses the National Weather Service API (api.weather.gov):

- `/alerts/active/area/{state}` - Weather alerts by state
- `/points/{lat},{lon}` - Forecast grid endpoints
- Forecast URLs from points response - Detailed forecasts

All API requests include proper User-Agent and Accept headers as required by the NWS API.

## Development

### Project Structure

```
weather/
├── weather.py          # Main MCP server implementation
├── main.py             # Entry point (placeholder)
├── config.json         # Configuration file
├── pyproject.toml      # Project metadata and dependencies
├── uv.lock            # Locked dependencies
└── README.md          # This file
```

### Adding New Tools

1. Define an async function in `weather.py`
2. Decorate it with `@mcp.tool()`
3. Use `make_nws_request()` for NWS API calls
4. Return formatted strings, not raw JSON
5. Handle errors gracefully

### Testing

Test the server by:
1. Running it and providing input via stdin
2. Integrating with an MCP client
3. Using MCP CLI tools

## Error Handling

- Network errors return user-friendly error messages
- No raw exceptions are exposed to clients
- All responses are formatted strings with clear labels

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

BSD-3-Clause License - see LICENSE file for details

## Author

Bryan Kemp (bryan@kempville.com)

## Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp)
- Weather data from [National Weather Service API](https://www.weather.gov/documentation/services-web-api)