Weather MCP Project

A Model Context Protocol (MCP) server that provides real-time weather alerts and forecasts from the US National Weather Service. Built with modern Python practices, comprehensive testing, and production-ready deployment.

Tests Coverage Type Checking Code Quality Python

Features

Weather Alerts - Real-time alerts from the National Weather Service
Weather Forecasts - Detailed forecasts for any US location
Web Interface - Beautiful Streamlit UI for easy interaction
MCP Protocol - Standards-compliant Model Context Protocol server
Async/Await - High-performance asynchronous architecture
100% Test Coverage - Comprehensive test suite with 53 tests
Type Safe - Full MyPy type checking compliance
Production Ready - Deployed and operational

Quick Start

Prerequisites

Python 3.13

1. Clone and Install

git clone <your-repo-url>
cd weather-mcp-project
pip install -r requirements.txt

2. Run the Web Interface

streamlit run ui.py

Open your browser to http://localhost:8501 and start exploring weather data!

3. Run the MCP Server

python -m weather_mcp.server

The MCP server will start on http://localhost:8000 with SSE transport.

Installation

Using pip

pip install -r requirements.txt

API Reference

Weather Alerts

Get active weather alerts for any US state:

await get_alerts(state: str) -> str

Parameters:

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

Returns:

Formatted string with active alerts or "No active alerts" message

Example:

alerts = await get_alerts("CA")
print(alerts)
# Output: Winter Storm Warning for Los Angeles County...

Weather Forecasts

Get detailed weather forecast for coordinates:

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

Parameters:

latitude (float): Latitude coordinate
longitude (float): Longitude coordinate

Returns:

Formatted forecast string with 5-day outlook

Example:

forecast = await get_forecast(34.0522, -118.2437)  # Los Angeles
print(forecast)
# Output: Today: Temperature: 75°F, Wind: 10 mph SW...

MCP Tools

The server exposes two MCP tools:

get_alerts - Fetch weather alerts by state
get_forecast - Fetch weather forecast by coordinates

Development

Project Structure

weather-mcp-project/
├── weather_mcp/           # Core MCP server
│   ├── __init__.py
│   ├── server.py         # FastMCP server
│   ├── nws_api.py        # National Weather Service API client
│   └── tools.py          # Weather processing tools
├── client/               # MCP client
│   ├── __init__.py
│   └── client.py         # Client implementation
├── tests/                # Comprehensive test suite
│   ├── conftest.py       # Test configuration
│   ├── test_*.py         # Test modules
│   └── run_tests.py      # Test runner
├── ui.py                 # Streamlit web interface
├── requirements.txt      # Dependencies
├── pyproject.toml        # Project configuration
└── README.md            # This file

Code Quality

This project maintains high code quality standards:

100% Test Coverage - Every line of code is tested
Type Checking - Full MyPy compliance
Linting - Ruff for code formatting and style
Standards - Follows Python best practices

Testing

Run with Coverage

python -m pytest --cov=weather_mcp --cov=client --cov-report=html --cov-report=term tests/

Test Coverage Report

After running tests with coverage, open htmlcov/index.html in your browser for a detailed coverage report.

Quality Checks

# Type checking
mypy .

# Linting and formatting
ruff check
ruff format

Weather MCP Project