Weather MCP Server

A Model Context Protocol (MCP) server that provides weather information using the OpenWeatherMap API. This server primarily runs in stdio mode (the standard for MCP servers) with an experimental HTTP API mode for testing.

Features

• MCP Protocol Support: Full stdio mode support for MCP clients
• HTTP API Mode: Experimental simple HTTP API for testing
• Current Weather: Get current weather conditions for any location
• Weather Forecast: Get weather forecasts up to 5 days ahead
• Location Flexibility: Support for city names, coordinates (lat,lon), and zip codes
• Docker Support: Containerized deployment with docker-compose
• Configurable: YAML-based configuration with environment variable support
• Well Tested: Comprehensive test suite with pytest

Prerequisites

• Python 3.11 or higher
• OpenWeatherMap API key (free tier available at OpenWeatherMap)
• Docker (optional, for containerized deployment)

Installation

Using pip

# Clone the repository
git clone https://github.com/dangogh/weather-mcp.git
cd weather-mcp

# Install dependencies
pip install -r requirements.txt

# Install the package
pip install -e .

Using Docker

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

# Or use docker-compose (see Docker section below)

Configuration

The server uses a YAML configuration file (config.yaml) with the following structure:

server:
  mode: stdio  # or 'http'
  http:
    host: 0.0.0.0
    port: 8080

weather_api:
  provider: openweathermap
  base_url: https://api.openweathermap.org/data/2.5
  api_key: ${WEATHER_API_KEY}  # Set via environment variable
  units: metric  # or 'imperial' or 'standard'
  timeout: 10

logging:
  level: INFO
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

Environment Variables

• WEATHER_API_KEY: Your OpenWeatherMap API key (required)
• SERVER_MODE: Override server mode (optional, defaults to config file)

Usage

Running in stdio mode

# Set your API key
export WEATHER_API_KEY="your_api_key_here"

# Run the server
python -m weather_mcp

# Or use the CLI command
weather-mcp

Running in HTTP mode (Experimental)

Note: HTTP mode provides a simple REST API for testing. For production MCP usage, use stdio mode.

# Update config.yaml to set mode: http, or use environment variable
export WEATHER_API_KEY="your_api_key_here"
export SERVER_MODE=http

python -m weather_mcp

The HTTP server will start on http://localhost:8080 with the following endpoints:

• GET /: Server information
• GET /health: Health check
• POST /weather/current: Get current weather (JSON: {"location": "London"})
• POST /weather/forecast: Get forecast (JSON: {"location": "London", "days": 3})

Using with Docker

Stdio mode:

# Set your API key in .env file
echo "WEATHER_API_KEY=your_api_key_here" > .env

# Run with docker-compose
docker-compose --profile stdio run weather-mcp-stdio

HTTP mode:

# Run HTTP server
docker-compose --profile http up weather-mcp-http

# The server will be available at http://localhost:8080

Available Tools

get_current_weather

Get current weather conditions for a location.

Parameters:

• location (string, required): City name, coordinates (lat,lon), or zip code

Example:

{
  "location": "London"
}

Response includes:

• Temperature and "feels like" temperature
• Weather description
• Humidity percentage
• Atmospheric pressure
• Wind speed

get_weather_forecast

Get weather forecast for a location up to 5 days ahead.

Parameters:

• location (string, required): City name, coordinates (lat,lon), or zip code
• days (integer, optional): Number of days to forecast (1-5, default: 3)

Example:

{
  "location": "New York",
  "days": 3
}

Response includes:

• Forecast data in 3-hour intervals
• Same weather details as current weather for each interval

Development

Running Tests

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Run with coverage
pytest --cov=src/weather_mcp --cov-report=html

Code Structure

weather-mcp/
├── src/
│   └── weather_mcp/
│       ├── __init__.py
│       ├── __main__.py       # Entry point
│       ├── config.py          # Configuration management
│       ├── server.py          # MCP server implementation
│       ├── weather_client.py  # Weather API client
│       └── http_server.py     # HTTP streaming server
├── tests/
│   ├── __init__.py
│   ├── test_config.py
│   ├── test_weather_client.py
│   └── test_server.py
├── config.yaml                # Configuration file
├── Dockerfile                 # Docker image definition
├── docker-compose.yml         # Docker compose configuration
├── requirements.txt           # Production dependencies
├── requirements-dev.txt       # Development dependencies
├── setup.py                   # Package setup
└── README.md                  # This file

API Reference

OpenWeatherMap API

This server uses the OpenWeatherMap API. Key features:

• Free Tier: 60 calls/minute, 1,000,000 calls/month
• Current Weather: Real-time weather data
• 5-Day Forecast: Weather predictions in 3-hour intervals
• Location Support: City names, coordinates, zip codes

Get your free API key at: https://openweathermap.org/api

License

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

Contributing

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

Troubleshooting

API Key Issues

If you see "API key not configured" errors:

1. Ensure WEATHER_API_KEY environment variable is set
2. Check that the key is valid and active on OpenWeatherMap
3. Verify the key is not expired (free tier keys don't expire but can be revoked)

Connection Issues

If you encounter connection errors:

1. Check your internet connection
2. Verify OpenWeatherMap API is accessible from your location
3. Check if you've exceeded rate limits (60 calls/minute for free tier)

Docker Issues

If Docker containers fail to start:

1. Ensure Docker and docker-compose are installed
2. Check that port 8080 is not already in use (for HTTP mode)
3. Verify the API key is properly set in the environment

Support

For issues and questions:

• Open an issue on GitHub: https://github.com/dangogh/weather-mcp/issues
• Check existing issues for solutions