dorianlgs/WeatherMCP

WeatherMCP 🌤️

A high-performance Model Context Protocol (MCP) server for weather data, implemented in Go. This server provides real-time weather alerts and forecasts using the National Weather Service (NWS) API.

Features

• 🌦️ Weather Alerts: Get active weather alerts for any US state
• 📍 Weather Forecasts: Get detailed forecasts for any location using coordinates
• ⚡ High Performance: Built with caching, retry logic, and connection pooling
• 🔧 Configurable: Environment-based configuration with sensible defaults
• 🐳 Containerized: Docker support for easy deployment
• 📊 Monitoring: Structured logging and health checks
• 🛡️ Robust: Input validation, error handling, and graceful shutdown

Quick Start

Prerequisites

• Go 1.24 or later
• Git

Installation

1. Clone the repository

   git clone https://github.com/dorianlgs/WeatherMCP.git
   cd WeatherMCP
   

2. Install dependencies

   go mod download
   

3. Build the application

   make build
   # or
   go build -o WeatherMCP .
   

4. Run in stdio mode (default)

   ./WeatherMCP
   

5. Run in SSE mode

   ./WeatherMCP -t sse
   

Configuration

The application can be configured using environment variables:

Example Configuration

export LOG_LEVEL=debug
export ENABLE_CACHING=true
export CACHE_TTL=10m
export MAX_RETRIES=5

Usage

MCP Tools

The server provides two main tools:

1. get_alerts - Weather Alerts

Get active weather alerts for a US state.

Parameters:

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

Example:

{
  "name": "get_alerts",
  "arguments": {
    "state": "CA"
  }
}

2. get_forecast - Weather Forecast

Get weather forecast for a location using coordinates.

Parameters:

• latitude (number, required): Latitude between -90 and 90
• longitude (number, required): Longitude between -180 and 180

Example:

{
  "name": "get_forecast",
  "arguments": {
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}

Claude Desktop Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "weather-mcp-stdio": {
      "command": "/path/to/WeatherMCP",
      "args": [],
      "env": {
        "LOG_LEVEL": "info",
        "ENABLE_CACHING": "true"
      }
    },
    "weather-mcp-sse": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/sse"
      ]
    }
  }
}

Development

Using Make

The project includes a comprehensive Makefile for common tasks:

# Build the application
make build

# Run tests
make test

# Run with coverage
make test-coverage

# Format code
make fmt

# Run linter
make lint

# Build for all platforms
make build-all

# Clean build artifacts
make clean

# Show all available commands
make help

Using Docker

Quick Start with Docker

# Build and run in stdio mode
docker-compose --profile stdio up

# Build and run in SSE mode
docker-compose --profile sse up

# Development mode with hot reload
docker-compose --profile dev up

Manual Docker Commands

# Build the image
docker build -t weather-mcp .

# Run in stdio mode
docker run weather-mcp

# Run in SSE mode
docker run -p 8080:8080 weather-mcp -t sse

# Run with custom environment
docker run -e LOG_LEVEL=debug -e ENABLE_CACHING=false weather-mcp

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific test
go test -v -run TestWeatherAlertHandler

# Run benchmarks
go test -bench=. -benchmem ./...

MCP Inspector

Test the server using the MCP Inspector:

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector
npx @modelcontextprotocol/inspector

# Or use Docker Compose
docker-compose --profile inspector up

Architecture

Project Structure

WeatherMCP/
├── main.go          # Application entry point and server setup
├── config.go        # Configuration management
├── handlers.go      # MCP tool handlers
├── structures.go    # Data structures and models
├── utils.go         # Utilities, HTTP client, and caching
├── Makefile         # Build and development tasks
├── Dockerfile       # Container configuration
├── docker-compose.yml # Multi-service deployment
├── go.mod           # Go module definition
├── go.sum           # Dependency checksums
├── .gitignore       # Git ignore rules
└── README.md        # This file

Key Components

1. Configuration Management: Environment-based configuration with validation
2. HTTP Client: Robust client with retry logic, caching, and connection pooling
3. Caching: In-memory caching with TTL for API responses
4. Error Handling: Comprehensive error handling with meaningful messages
5. Input Validation: Strict validation for all input parameters
6. Logging: Structured logging with configurable levels

Performance Features

• Caching: Configurable TTL-based caching reduces API calls
• Connection Pooling: Reuses HTTP connections for better performance
• Retry Logic: Exponential backoff for failed requests
• Graceful Shutdown: Proper cleanup on server termination
• Memory Efficient: Minimal memory footprint with proper cleanup

API Reference

National Weather Service API

The application uses the National Weather Service (NWS) API:

• Base URL: https://api.weather.gov
• Format: GeoJSON
• Rate Limits: 1000 requests per hour per IP
• Documentation: NWS API Documentation

Endpoints Used

1. Alerts: /alerts/active/area/{state}
2. Points: /points/{lat},{lon}
3. Forecast: Dynamic URL from points response

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow Go best practices and conventions
• Add tests for new functionality
• Update documentation for API changes
• Use meaningful commit messages
• Ensure all tests pass before submitting PR

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• National Weather Service for providing the weather API
• MCP Go SDK for the MCP implementation
• Model Context Protocol for the protocol specification

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

Changelog

v2.0.0

• Complete rewrite with improved architecture
• Added caching and retry logic
• Enhanced error handling and validation
• Docker and Docker Compose support
• Comprehensive testing and documentation
• Performance optimizations

v1.0.0

• Initial release with basic weather alerts and forecasts
• Stdio and SSE transport support