MCP Weather Server

A FastAPI-based weather server that integrates with Home Assistant using the Model Context Protocol (MCP). This server uses OpenWeatherMap's One Call API 3.0 to provide comprehensive weather information including current conditions, daily forecasts, and hourly forecasts for any location.

Prerequisites

Python 3.7+
OpenWeatherMap API key (with One Call API 3.0 access)

Setup

Clone this repository
Install dependencies:
```
pip install -r requirements.txt
```
Configure your OpenWeather API key using one of these methods:
- Set environment variable (recommended):
```
export OPENWEATHER_API_KEY=your_api_key_here
```
- Or add it to config.yaml:
```
settings:
  api_key: your_api_key_here
```
Note: Environment variable takes precedence over config file.

(Optional) Configure additional settings in config.yaml:

# General settings
settings:
  units: "imperial"  # Optional: "metric" (default) or "imperial"
  api_key: "your_api_key_here"  # Alternative to environment variable
  server:
    host: "0.0.0.0"  # Optional: Interface to listen on (default: "0.0.0.0")
    port: 8000       # Optional: Port to listen on (default: 8000)

# Location overrides (optional)
overrides:
  "lafayette": "Lafayette, CA, US"
  # Add more overrides as needed

Configuration

API Key

The OpenWeather API key can be configured in two ways:

Environment variable OPENWEATHER_API_KEY (recommended for security)
config.yaml under settings.api_key

Server Settings

Configure the server's listening interface and port in config.yaml:

settings:
  server:
    host: "0.0.0.0"  # Listen on all interfaces (default)
    port: 8000       # Port number (default)

host: The network interface to listen on
- "0.0.0.0": Listen on all interfaces (default)
- "127.0.0.1": Listen only on localhost
- "192.168.1.100": Listen on a specific interface
port: The port number to listen on (default: 8000)

Units

You can choose between metric and imperial units in config.yaml:

metric (default if not specified):
- Temperature: Celsius
- Wind Speed: meters per second
imperial:
- Temperature: Fahrenheit
- Wind Speed: miles per hour

Location Overrides

The optional overrides section in config.yaml allows you to specify default locations for ambiguous city names. For example:

overrides:
  "lafayette": "Lafayette, CA, US"
  "springfield": "Springfield, IL, US"

Default Configuration

If no config.yaml file is present, the server will:

Use metric units
Listen on all interfaces (0.0.0.0:8000)
Have no location overrides
Require the API key to be set in the environment

Running the Server

Start the server with:

python server.py

The server will run on the configured host and port (default: http://0.0.0.0:8000)

API Endpoints

Legacy REST API

These endpoints provide traditional HTTP access:

Current Weather

GET /api/current-weather/{location}

Returns current weather including temperature, feels like temperature, humidity, wind speed, UV index, and cloud coverage.

Daily Forecast

GET /api/daily-forecast/{location}?days={number_of_days}

Returns daily forecast for up to 7 days, including day/min/max temperatures, precipitation probability, and UV index.

Hourly Forecast

GET /api/hourly-forecast/{location}?hours={number_of_hours}

Returns hourly forecast for up to 48 hours, including temperature, feels like temperature, precipitation probability, and UV index.

MCP Integration

The server implements the Model Context Protocol (MCP) for seamless integration with Home Assistant. The MCP endpoint is available at:

/mcp/sse

MCP Tools available:

current_weather(location: str): Get current weather conditions
hourly_forecast(location: str, hours: int = 24): Get hourly forecast
daily_forecast(location: str, days: int = 7): Get daily forecast

Location Resolution

The server uses a flexible location resolution system:

If a location matches an entry in overrides config, that override is used
For city names without state/country, it attempts to resolve directly
For "City, State" format, it assumes USA (e.g., "Portland, OR" → "Portland, Oregon, US")
Full "City, State, Country" format is always respected

Examples:

"London" → "London, England, GB"
"Lafayette" → "Lafayette, California, US" (if configured in overrides)
"Portland, OR" → "Portland, Oregon, US"
"Melbourne, AU" → "Melbourne, Victoria, AU"

API Response Format

Weather data is returned in either metric or imperial units based on configuration:

Metric (default):

Temperature: Celsius
Wind Speed: meters per second
Humidity: percentage
UV Index: 0-11+ scale
Precipitation Probability: 0-1 (0-100%)
Cloud Coverage: percentage

Imperial:

Temperature: Fahrenheit
Wind Speed: miles per hour
Other units same as metric

Example current weather response:

{
    "resolved_location": "London, England, GB",
    "temperature": 17.88,
    "feels_like": 17.29,
    "description": "few clouds",
    "humidity": 60,
    "wind_speed": 5.14,
    "uvi": 0,
    "clouds": 11,
    "timestamp": "2024-04-30T13:10:15"
}

Example daily forecast response:

{
    "resolved_location": "London, England, GB",
    "forecast": [
        {
            "date": "2024-04-30",
            "temp_day": 20.3,
            "temp_min": 15.1,
            "temp_max": 22.4,
            "description": "scattered clouds",
            "humidity": 70,
            "wind_speed": 4.2,
            "precipitation_probability": 0.3,
            "uvi": 6.1
        }
    ]
}