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

1. Clone this repository

2. Install dependencies:

   pip install -r requirements.txt
   

3. 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.

4. (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:

1. Environment variable OPENWEATHER_API_KEY (recommended for security)
2. 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:

1. If a location matches an entry in overrides config, that override is used
2. For city names without state/country, it attempts to resolve directly
3. For "City, State" format, it assumes USA (e.g., "Portland, OR" → "Portland, Oregon, US")
4. 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
        }
    ]
}