Weather MCP Server

A Model Context Protocol (MCP) server that provides weather data tools using the National Weather Service (NWS) API.

Overview

This MCP server exposes two main tools for accessing weather information:

• get_alerts: Fetch active weather alerts for a US state
• get_forecast: Retrieve detailed weather forecasts for a specific latitude/longitude

The server is built using FastMCP and communicates over stdio transport, making it compatible with MCP clients like Claude Desktop.

Features

• 🌤️ Real-time weather forecasts from the National Weather Service
• ⚠️ Active weather alerts by state
• 🔄 Async API calls for efficient data retrieval
• 🛡️ Robust error handling and user-friendly responses
• 📦 Easy integration with MCP-compatible clients

Requirements

• Python 3.11 or higher
• uv package manager (recommended)

Installation

Using uv (recommended)

# Clone the repository
git clone <repository-url>
cd weather

# Install dependencies
uv sync

# Activate virtual environment
source .venv/bin/activate

Using pip

# Clone the repository
git clone <repository-url>
cd weather

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

Usage

Running the Server

uv run weather.py

Integration with MCP Clients

To use this server with an MCP client like Claude Desktop, add it to your MCP configuration:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["--directory", "/path/to/weather", "run", "weather.py"]
    }
  }
}

Available Tools

get_alerts

Fetch active weather alerts for a US state.

Parameters:

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

Example:

get_alerts(state="CA")

get_forecast

Retrieve weather forecast for a specific location.

Parameters:

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

Example:

get_forecast(latitude=37.7749, longitude=-122.4194)

API Integration

This server uses the National Weather Service API (api.weather.gov):

• /alerts/active/area/{state} - Weather alerts by state
• /points/{lat},{lon} - Forecast grid endpoints
• Forecast URLs from points response - Detailed forecasts

All API requests include proper User-Agent and Accept headers as required by the NWS API.

Development

Project Structure

weather/
├── weather.py          # Main MCP server implementation
├── main.py             # Entry point (placeholder)
├── config.json         # Configuration file
├── pyproject.toml      # Project metadata and dependencies
├── uv.lock            # Locked dependencies
└── README.md          # This file

Adding New Tools

1. Define an async function in weather.py
2. Decorate it with @mcp.tool()
3. Use make_nws_request() for NWS API calls
4. Return formatted strings, not raw JSON
5. Handle errors gracefully

Testing

Test the server by:

1. Running it and providing input via stdin
2. Integrating with an MCP client
3. Using MCP CLI tools

Error Handling

• Network errors return user-friendly error messages
• No raw exceptions are exposed to clients
• All responses are formatted strings with clear labels

Contributing

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

License

BSD-3-Clause License - see LICENSE file for details

Author

Bryan Kemp (bryan@kempville.com)

Acknowledgments

• Built with FastMCP
• Weather data from National Weather Service API