PyWeatherMCP

Zerosks471/PyWeatherMCP

3.2

If you are the rightful owner of PyWeatherMCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

PyWeatherMCP is a Model Context Protocol server that provides weather information using the National Weather Service API.

Tools
6
Resources
0
Prompts
0

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 .

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.