Weather MCP Server

Weather MCP Server

A Model Context Protocol (MCP) server that provides weather information and alerts using the National Weather Service (NWS) API. This server offers tools for retrieving weather forecasts and active weather alerts for locations in the United States.

About This Project

This project is based on the Model Context Protocol (MCP) Getting Started Tutorial for server developers. The tutorial provides a comprehensive guide for building MCP servers and integrating them with clients like Claude for Desktop.

The original code sample for this weather server can be found in the MCP Quickstart Resources repository.

Features

• Weather Alerts: Get active weather alerts for any US state using two-letter state codes
• Weather Forecasts: Retrieve detailed weather forecasts for specific coordinates
• Real-time Data: Uses the official National Weather Service API for accurate, up-to-date information
• Easy Integration: Simple MCP server that can be integrated with any MCP-compatible client

Installation

Prerequisites

• Python 3.8 or higher
• uv package manager (recommended) or pip

Setup

1. Clone the repository:

2. Install dependencies using uv:

Or using pip:

Usage

Running the Server

Start the MCP server:

The server will start and communicate via stdio, ready to handle requests from MCP clients.

Available Tools

1. Get Weather Alerts (get_alerts)

Retrieve active weather alerts for a US state.

Parameters:

• state (string): Two-letter US state code (e.g., "CA", "NY", "TX")

Example:

Response Format:

2. Get Weather Forecast (get_forecast)

Get detailed weather forecast for a specific location.

Parameters:

• latitude (float): Latitude coordinate of the location
• longitude (float): Longitude coordinate of the location

Example:

Response Format:

API Information

This server uses the National Weather Service API, which provides:

• No API Key Required: Free access to weather data
• Real-time Updates: Data is updated frequently throughout the day
• Comprehensive Coverage: Covers all US states and territories
• Reliable Service: Official government weather service

Data Sources

• Alerts: Active weather alerts from the NWS
• Forecasts: Detailed weather forecasts including temperature, wind, and conditions
• Geographic Data: Point-based weather information for any US location

Error Handling

The server includes robust error handling for:

• Network connectivity issues
• Invalid coordinates or state codes
• API service unavailability
• Timeout conditions

When errors occur, the server returns informative error messages to help with debugging.

Development

Project Structure

Dependencies

• mcp: Model Context Protocol server framework
• httpx: Async HTTP client for API requests
• fastmcp: FastMCP server implementation

Adding New Features

To add new weather-related tools:

1. Create a new async function in weather.py
2. Decorate it with @mcp.tool()
3. Add proper type hints and docstrings
4. Implement error handling using the existing make_nws_request helper

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.

Support

For issues or questions:

1. Check the National Weather Service API documentation
2. Review the MCP documentation at modelcontextprotocol.io
3. Open an issue in this repository

Note: This server is designed for educational and development purposes. For production use, consider implementing rate limiting and additional error handling based on your specific requirements.