# 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)
