PyWeatherMCP

# 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) 1. Clone the repository: ```bash git clone https://github.com/yourusername/pyweathermcp.git cd pyweathermcp ``` 2. Install dependencies using uv: ```bash uv sync ``` ### Using pip 1. Clone the repository: ```bash git clone https://github.com/yourusername/pyweathermcp.git cd pyweathermcp ``` 2. Create a virtual environment: ```bash python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate ``` 3. Install dependencies: ```bash pip install -e . ``` ## Usage ### Running the MCP Server To run the weather MCP server: ```bash 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:** ```python get_alerts("CA") ``` #### 2. Get Weather Forecast Get a 5-day weather forecast for a specific location. **Parameters:** - `latitude` (float): Latitude coordinate - `longitude` (float): Longitude coordinate - `location_name` (string, optional): Human-readable name for the location **Example:** ```python 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 location - `latitude` (float): Latitude coordinate - `longitude` (float): Longitude coordinate **Example:** ```python save_favorite("Home", 40.7128, -74.0060) ``` #### 4. Get Favorite Locations Retrieve all saved favorite locations. **Example:** ```python get_favorites() ``` #### 5. Get Search History View your recent weather searches. **Parameters:** - `limit` (int, optional): Number of recent searches to show (default: 10) **Example:** ```python get_history(5) ``` #### 6. Clear Search History Clear all search history while keeping favorites. **Example:** ```python 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 requests - `mcp>=1.18.0`: Model Context Protocol server framework ### Testing Imports To verify all dependencies are properly installed: ```bash python test_imports.py ``` ## Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## License This project is open source and available under the [MIT License](LICENSE). ## Support If you encounter any issues or have questions: 1. Check the [Issues](https://github.com/yourusername/pyweathermcp/issues) page 2. Create a new issue with detailed information 3. 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.