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:

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:

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:

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:

4. Get Favorite Locations

Retrieve all saved favorite locations.

Example:

5. Get Search History

View your recent weather searches.

Parameters:

• limit (int, optional): Number of recent searches to show (default: 10)

Example:

6. Clear Search History

Clear all search history while keeping favorites.

Example:

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

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:

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.