Weather CLI Application

A command-line interface application that provides weather forecasts and alerts using the National Weather Service (NWS) API. This project is built using the Model Context Protocol (MCP) framework.

About Model Context Protocol

The Model Context Protocol (MCP) is an open standard that enables AI models to interact with external tools and services. This weather application is implemented as an MCP server, allowing it to be used as a tool by AI assistants like Claude.

When integrated with an MCP-compatible client, this server enables AI assistants to:

• Retrieve real-time weather forecasts for specific locations
• Access active weather alerts for any U.S. state
• Present this information to users in a structured format

Features

• Weather Forecasts: Get detailed weather forecasts for any location in the United States by providing latitude and longitude coordinates.
• Weather Alerts: Retrieve active weather alerts for any U.S. state using the two-letter state code.
• MCP Integration: Seamlessly integrates with AI assistants through the Model Context Protocol.

Installation

Prerequisites

• Python 3.12 or higher
• Git (for cloning the repository)
• uv - An extremely fast Python package installer and resolver, written in Rust

Setup

1. Clone the repository:

   git clone <repository-url>
   cd weather
   

2. Create and activate a virtual environment using uv:

   uv venv
   # On Windows
   .venv\Scripts\activate
   # On macOS/Linux
   source .venv/bin/activate
   

3. Install dependencies using uv:

   uv add "mcp[cli]" httpx
   

Usage

As a Python Module

The application provides two main functions:

Get Weather Forecast

Retrieve a weather forecast for a specific location by providing latitude and longitude:

from weather import get_forecast

# Example: Get forecast for New York City
forecast = await get_forecast(40.7128, -74.0060)
print(forecast)

Get Weather Alerts

Retrieve active weather alerts for a specific state:

from weather import get_alerts

# Example: Get alerts for California
alerts = await get_alerts("CA")
print(alerts)

As an MCP Server

To run as an MCP server that can be used by AI assistants:

python -m weather

Integration with Claude Desktop

To use this weather server with Claude Desktop:

1. Open Claude Desktop
2. Go to Settings > Edit Config
3. Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["-m", "weather"]
    }
  }
}

4. Save and restart Claude Desktop
5. You can now ask Claude to check the weather or alerts using this tool

API Reference

get_forecast(latitude: float, longitude: float) -> str

Returns a formatted string containing the weather forecast for the specified location.

Parameters:

• latitude: The latitude of the location
• longitude: The longitude of the location

get_alerts(state: str) -> str

Returns a formatted string containing active weather alerts for the specified state.

Parameters:

• state: The two-letter state code (e.g., CA, NY)

Technical Details

• Built with Python's asynchronous capabilities
• Uses httpx for HTTP requests
• Integrates with the National Weather Service (NWS) API
• Implements FastMCP for tool integration
• Created using the create-mcp-server template
• Uses uv for fast, reliable package management

Why uv?

This project uses uv instead of pip for several key advantages:

• Speed: uv is 10-100x faster than pip, significantly reducing installation time
• Reliability: Better dependency resolution with clear error messages
• Efficiency: Global cache for dependency deduplication saves disk space
• Compatibility: Works as a drop-in replacement for pip commands

Acknowledgements

• National Weather Service (NWS) for providing the weather data API
• The Model Context Protocol project for the tool integration framework
• Anthropic for managing the MCP open source initiative
• Astral for developing uv, the Python package installer used in this project