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 package manager (recommended)
Installation
Using uv (recommended)
# Clone the repository
git clone <repository-url>
cd weather
# Install dependencies
uv sync
# Activate virtual environment
source .venv/bin/activate
Using pip
# 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
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:
{
"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:
get_alerts(state="CA")
get_forecast
Retrieve weather forecast for a specific location.
Parameters:
latitude(float): Latitude coordinatelongitude(float): Longitude coordinate
Example:
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
- Define an async function in
weather.py - Decorate it with
@mcp.tool() - Use
make_nws_request()for NWS API calls - Return formatted strings, not raw JSON
- Handle errors gracefully
Testing
Test the server by:
- Running it and providing input via stdin
- Integrating with an MCP client
- 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
- Weather data from National Weather Service API