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:

   git clone https://github.com/yourusername/pyweathermcp.git
   cd pyweathermcp

2. Install dependencies using uv:

   uv sync

Using pip

1. Clone the repository:

   git clone https://github.com/yourusername/pyweathermcp.git
   cd pyweathermcp

2. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. 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 coordinate
• longitude (float): Longitude coordinate
• location_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 location
• latitude (float): Latitude coordinate
• longitude (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 requests
• mcp>=1.18.0: Model Context Protocol server framework

Testing Imports

To verify all dependencies are properly installed:

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.

Support

If you encounter any issues or have questions:

1. Check the 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.