PyWeatherMCP
A Model Context Protocol (MCP) server that provides weather information using the National Weather Service API. This server offers weather alerts, forecasts, and location management features for MCP-compatible clients.
Features
- 🌦️ Weather Alerts: Get active weather alerts for any US state
- 📍 Weather Forecasts: Get 5-day weather forecasts for any US location
- ⭐ Favorite Locations: Save and manage your favorite weather locations
- 📊 Search History: Track your weather queries
- 🔄 Memory Persistence: Automatically saves your preferences and history
Prerequisites
- Python 3.14 or higher
- Internet connection (for API calls to National Weather Service)
Installation
Using uv (Recommended)
-
Clone the repository:
git clone https://github.com/yourusername/pyweathermcp.git cd pyweathermcp -
Install dependencies using uv:
uv sync
Using pip
-
Clone the repository:
git clone https://github.com/yourusername/pyweathermcp.git cd pyweathermcp -
Create a virtual environment:
python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate -
Install dependencies:
pip install -e .
Usage
Running the MCP Server
To run the weather MCP server:
python weather.py
The server will start and listen for MCP protocol messages via stdio.
Available Tools
1. Get Weather Alerts
Get active weather alerts for a US state.
Parameters:
state(string): Two-letter US state code (e.g., "CA", "NY", "TX")
Example:
get_alerts("CA")
2. Get Weather Forecast
Get a 5-day weather forecast for a specific location.
Parameters:
latitude(float): Latitude coordinatelongitude(float): Longitude coordinatelocation_name(string, optional): Human-readable name for the location
Example:
get_forecast(37.7749, -122.4194, "San Francisco, CA")
3. Save Favorite Location
Save a location to your favorites for quick access.
Parameters:
name(string): Name of the locationlatitude(float): Latitude coordinatelongitude(float): Longitude coordinate
Example:
save_favorite("Home", 40.7128, -74.0060)
4. Get Favorite Locations
Retrieve all saved favorite locations.
Example:
get_favorites()
5. Get Search History
View your recent weather searches.
Parameters:
limit(int, optional): Number of recent searches to show (default: 10)
Example:
get_history(5)
6. Clear Search History
Clear all search history while keeping favorites.
Example:
clear_history()
Available Resources
Server Information
Get information about the weather server and its capabilities.
Resource URI: weather://info
Usage Statistics
Get usage statistics including search count and favorite locations.
Resource URI: weather://stats
Available Prompts
Quick Weather Check
A template prompt for quick weather checks using your favorite locations.
Prompt: quick_weather_prompt
Data Storage
The server automatically creates and maintains a weather_memory.json file to store:
- Search history
- Favorite locations
- Usage statistics
This file is created automatically on first use and is excluded from version control.
API Information
This server uses the National Weather Service API (https://api.weather.gov), which:
- Provides free weather data for the United States
- Requires no API key or authentication
- Has rate limits (please be respectful)
- Covers all US states and territories
Error Handling
The server includes robust error handling:
- Network timeouts (30 seconds)
- Invalid coordinates or state codes
- API service unavailability
- Graceful fallbacks for missing data
Development
Project Structure
pyweathermcp/
├── weather.py # Main MCP server implementation
├── main.py # Simple entry point
├── test_imports.py # Import testing utility
├── pyproject.toml # Project configuration and dependencies
├── weather_memory.json # User data storage (auto-generated)
├── .gitignore # Git ignore rules
└── README.md # This file
Dependencies
httpx>=0.28.1: Modern HTTP client for API requestsmcp>=1.18.0: Model Context Protocol server framework
Testing Imports
To verify all dependencies are properly installed:
python test_imports.py
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
This project is open source and available under the MIT License.
Support
If you encounter any issues or have questions:
- Check the Issues page
- Create a new issue with detailed information
- Include error messages and steps to reproduce
Changelog
v0.1.0
- Initial release
- Weather alerts and forecasts
- Favorite locations management
- Search history tracking
- Memory persistence
Note: This server is designed to work with MCP-compatible clients. Make sure your client supports the MCP protocol for the best experience.