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
# 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
# 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
{
"mcpServers": {
"weather": {
"command": "uv",
"args": [
"--directory",
"/path/to/weather-mcp",
"run",
"-m",
"weather.main"
]
}
}
}
Option 2: Docker Container
{
"mcpServers": {
"weather": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"weather-mcp-server"
]
}
}
}
Development
Running Tests
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run tests with coverage
pytest --cov=src/weather
Code Formatting and Linting
# 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.