matthewlimm/mcp-weather-server

MCP Weather Server

A complete MCP (Model Context Protocol) server that provides weather alerts and forecasts using the National Weather Service API. Built following the official MCP documentation with educational comments for learning MCP development.

Features

• Weather Alerts: Get active weather alerts for any US state
• Weather Forecasts: Get detailed 5-day forecasts for any coordinates
• Bellevue Integration: Pre-configured support for Bellevue, WA (47.6101° N, 122.2015° W)
• Educational Code: Comprehensive comments explaining MCP concepts
• Production Ready: Proper error handling and async implementation

Demo

Live Weather Demo: Bellevue, WA Weather

Setup

Prerequisites

• Python 3.10 or higher
• Virtual environment (recommended)

Installation

1. Create and activate virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Test the server:

python weather_server.py

MCP Client Configuration

For Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "/FULL/PATH/TO/YOUR/PROJECT/.venv/bin/python",
      "args": [
        "/FULL/PATH/TO/YOUR/PROJECT/weather_server.py"
      ]
    }
  }
}

Replace /FULL/PATH/TO/YOUR/PROJECT/ with your actual project path.

Usage

The server exposes two MCP tools:

1. get_alerts(state: str)

Get weather alerts for a US state using 2-letter state codes.

Examples:

• get_alerts("WA") - Washington state alerts
• get_alerts("CA") - California alerts
• get_alerts("NY") - New York alerts

2. get_forecast(latitude: float, longitude: float)

Get detailed weather forecast for specific coordinates.

Examples:

• get_forecast(47.6101, -122.2015) - Bellevue, WA forecast
• get_forecast(40.7128, -74.0060) - New York City forecast
• get_forecast(37.7749, -122.4194) - San Francisco forecast

Architecture

Built with FastMCP following the official MCP documentation:

• Async HTTP Requests: Uses httpx for non-blocking API calls
• Error Handling: Graceful handling of API failures and network issues
• Educational Comments: Detailed explanations of MCP concepts
• National Weather Service API: Official US government weather data

Development

Code Structure

weather_server.py
├── Imports & Configuration
├── Helper Functions
│   ├── make_nws_request()    # Async API requests
│   └── format_alert()        # Alert formatting
├── MCP Tools
│   ├── @mcp.tool() get_alerts()    # State weather alerts
│   └── @mcp.tool() get_forecast()  # Coordinate forecasts
└── Server Startup

Key Dependencies

• mcp[cli]>=1.2.0 - MCP server framework
• httpx>=0.25.0 - Async HTTP client

Testing

The server has been successfully tested and verified working with:

• Weather alerts for Washington state
• Weather forecasts for Bellevue, WA coordinates
• MCP client integration (Claude Desktop)
• Error handling for invalid requests

Contributing

This server serves as an educational example of MCP development. The code includes comprehensive comments explaining each MCP concept for developers learning the Model Context Protocol.

License

Built following the official MCP documentation and examples.