# Weather MCP Server
A Model Context Protocol (MCP) server that provides weather information and alerts from the National Weather Service (NWS).
## Features
- **get_alerts**: Retrieve active weather alerts for a US state
- **get_forecast**: Get weather forecasts for a specific location (latitude/longitude)
## Prerequisites
- Python 3.10 or higher
- Docker and Docker Compose (for containerized deployment)
## Installation
### Local Setup
```bash
# Clone the repository
git clone https://github.com/yourusername/weather-mcp.git
cd weather-mcp
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -e .
# Run the server
weather-mcp
```
### Docker Setup
```bash
# Build and run with Docker Compose
docker-compose up -d
# View logs
docker-compose logs -f weather-mcp
```
## Configuration
### Claude Desktop Integration
To use this server with Claude Desktop, add the following to `~/.config/Claude/claude_desktop_config.json` (Linux/macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
#### Option 1: Local Installation
```json
{
"mcpServers": {
"weather": {
"command": "uv",
"args": [
"--directory",
"/path/to/weather-mcp",
"run",
"-m",
"weather.main"
]
}
}
}
```
#### Option 2: Docker Container
```json
{
"mcpServers": {
"weather": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"weather-mcp-server"
]
}
}
}
```
## Development
### Running Tests
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run tests with coverage
pytest --cov=src/weather
```
### Code Formatting and Linting
```bash
# Format code with Black
black src tests
# Lint with Ruff
ruff check src tests
```
## Project Structure
```
weather-mcp/
├── src/weather/ # Main package
│ ├── __init__.py
│ ├── main.py # Entry point
│ └── server.py # Server implementation
├── config/ # Configuration files
│ ├── __init__.py
│ └── settings.py
├── tests/ # Test suite
├── Dockerfile # Docker image definition
├── docker-compose.yml # Docker Compose configuration
├── pyproject.toml # Project metadata and dependencies
├── README.md # This file
└── DOCKER_SETUP.md # Docker setup guide
```
## API Reference
### get_alerts(state: str) -> str
Get active weather alerts for a US state.
**Parameters:**
- `state`: Two-letter US state code (e.g., CA, NY, TX)
**Returns:** Formatted string containing active weather alerts or a message if none found.
### get_forecast(latitude: float, longitude: float) -> str
Get weather forecast for a specific location.
**Parameters:**
- `latitude`: Location latitude (up to 4 decimal places recommended)
- `longitude`: Location longitude (up to 4 decimal places recommended)
**Returns:** Formatted string with the next 5 forecast periods including temperature, wind, and conditions.
## Troubleshooting
### Server won't start
- Check Python version: `python --version` (requires 3.10+)
- Ensure dependencies are installed: `pip install -e .`
- Check logs for detailed error messages
### Docker issues
- Rebuild image: `docker-compose build --no-cache`
- View logs: `docker-compose logs weather-mcp`
- Ensure Docker daemon is running
### Claude Desktop not detecting server
- Verify the path in `claude_desktop_config.json`
- Restart Claude Desktop after configuration changes
- Check the MCP server settings in Claude Desktop
## Logging
The server logs to stderr to avoid interfering with the MCP protocol's use of stdout. Logs are automatically sent to stderr and include timestamps and severity levels.
## License
MIT License - see LICENSE file for details
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Support
For issues, questions, or suggestions, please open an issue on GitHub.