dog830228/mcp_weather_server repository overview

⁠Weather MCP Server

A Model Context Protocol (MCP) server that provides weather information using the Open-Meteo API. This server supports multiple transport modes: standard stdio, HTTP Server-Sent Events (SSE), and the new Streamable HTTP protocol for web-based integration.

⁠Features

⁠Weather & Air Quality

• Get current weather information with comprehensive metrics:
  • Temperature, humidity, dew point
  • Wind speed, direction, and gusts
  • Precipitation (rain/snow) and probability
  • Atmospheric pressure and cloud cover
  • UV index and visibility
  • "Feels like" temperature
• Get weather data for a date range with hourly details
• Get air quality information including:
  • PM2.5 and PM10 particulate matter
  • Ozone, nitrogen dioxide, carbon monoxide
  • Sulfur dioxide, ammonia, dust
  • Aerosol optical depth
  • Health advisories and recommendations

⁠Time & Timezone

• Get current date/time in any timezone
• Convert time between timezones
• Get timezone information

⁠Transport Modes

• Multiple transport modes:
  • stdio - Standard MCP for desktop clients (Claude Desktop, etc.)
  • SSE - Server-Sent Events for web applications
  • streamable-http - Modern MCP Streamable HTTP protocol with stateful/stateless options
• RESTful API endpoints via Starlette integration

⁠Server Modes

This MCP server supports stdio, SSE, and streamable-http modes in a single unified server:

⁠Mode Comparison

⁠Configuration

This server does not require an API key. It uses the Open-Meteo API, which is free and open-source.

⁠Usage

This server provides several tools for weather and time-related operations:

⁠Available Tools

⁠Weather Tools

1. get_current_weather - Get current weather for a city with comprehensive metrics
2. get_weather_by_datetime_range - Get weather data for a date range with hourly details
3. get_weather_details - Get detailed weather information as structured JSON data

⁠Air Quality Tools

1. get_air_quality - Get air quality information with pollutant levels and health advice
2. get_air_quality_details - Get detailed air quality data as structured JSON

⁠Time & Timezone Tools

1. get_current_datetime - Get current time in any timezone
2. get_timezone_info - Get timezone information
3. convert_time - Convert time between timezones

⁠Tool Details

⁠get_current_weather

Retrieves comprehensive current weather information for a given city with enhanced metrics.

Parameters:

• city (string, required): The name of the city (English names only)

Returns: Detailed weather data including:

• Temperature and "feels like" temperature
• Humidity, dew point
• Wind speed, direction (as compass direction), and gusts
• Precipitation details (rain/snow) and probability
• Atmospheric pressure and cloud cover
• UV index with warning levels
• Visibility

Example Response:

The weather in Tokyo is Mainly clear with a temperature of 22.5°C (feels like 21.0°C),
relative humidity at 65%, and dew point at 15.5°C. Wind is blowing from the NE at 12.5 km/h
with gusts up to 18.5 km/h. Atmospheric pressure is 1013.2 hPa with 25% cloud cover.
UV index is 5.5 (Moderate). Visibility is 10.0 km.

⁠get_weather_by_datetime_range

Retrieves hourly weather information with comprehensive metrics for a specified city between start and end dates.

Parameters:

• city (string, required): The name of the city (English names only)
• start_date (string, required): Start date in format YYYY-MM-DD (ISO 8601)
• end_date (string, required): End date in format YYYY-MM-DD (ISO 8601)

Returns: Comprehensive weather analysis including:

• Hourly weather data with all enhanced metrics
• Temperature trends (highs, lows, averages)
• Precipitation patterns and probabilities
• Wind conditions assessment
• UV index trends
• Weather warnings and recommendations

Example Response:

[Analysis of weather trends over 2024-01-01 to 2024-01-07]
- Temperature ranges from 5°C to 15°C
- Precipitation expected on Jan 3rd and 5th (60% probability)
- Wind speeds averaging 15 km/h from SW direction
- UV index moderate (3-5) throughout the period
- Recommendation: Umbrella needed for midweek

⁠get_weather_details

Get detailed weather information for a specified city as structured JSON data for programmatic use.

Parameters:

• city (string, required): The name of the city (English names only)

Returns: Raw JSON data with all weather metrics suitable for processing and analysis

⁠get_air_quality

Get current air quality information for a specified city with pollutant levels and health advisories.

Parameters:

• city (string, required): The name of the city (English names only)
• variables (array, optional): Specific pollutants to retrieve. Options:
  • pm10 - Particulate matter ≤10μm
  • pm2_5 - Particulate matter ≤2.5μm
  • carbon_monoxide - CO levels
  • nitrogen_dioxide - NO2 levels
  • ozone - O3 levels
  • sulphur_dioxide - SO2 levels
  • ammonia - NH3 levels
  • dust - Dust particle levels
  • aerosol_optical_depth - Atmospheric turbidity

Returns: Comprehensive air quality report including:

• Current pollutant levels with units
• Air quality classification (Good/Moderate/Unhealthy/Hazardous)
• Health recommendations for general population
• Specific warnings for sensitive groups
• Comparison with WHO and EPA standards

Example Response:

Air quality in Beijing (lat: 39.90, lon: 116.41):
PM2.5: 45.3 μg/m³ (Unhealthy for Sensitive Groups)
PM10: 89.2 μg/m³ (Moderate)
Ozone (O3): 52.1 μg/m³
Nitrogen Dioxide (NO2): 38.5 μg/m³
Carbon Monoxide (CO): 420.0 μg/m³

Health Advice: Sensitive groups (children, elderly, people with respiratory conditions)
should limit outdoor activities.

⁠get_air_quality_details

Get detailed air quality information as structured JSON data for programmatic analysis.

Parameters:

• city (string, required): The name of the city (English names only)
• variables (array, optional): Specific pollutants to retrieve (same options as get_air_quality)

Returns: Raw JSON data with complete air quality metrics and hourly data

⁠get_current_datetime

Retrieves the current time in a specified timezone.

Parameters:

• timezone_name (string, required): IANA timezone name (e.g., 'America/New_York', 'Europe/London'). Use UTC if no timezone provided.

Returns: Current date and time in the specified timezone

Example:

{
  "timezone": "America/New_York",
  "current_time": "2024-01-15T14:30:00-05:00",
  "utc_time": "2024-01-15T19:30:00Z"
}

⁠get_timezone_info

Get information about a specific timezone.

Parameters:

• timezone_name (string, required): IANA timezone name

Returns: Timezone details including offset and DST information

⁠convert_time

Convert time from one timezone to another.

Parameters:

• time_str (string, required): Time to convert (ISO format)
• from_timezone (string, required): Source timezone
• to_timezone (string, required): Target timezone

Returns: Converted time in target timezone

⁠Docker Deployment

The project is available as a Docker image on Docker Hub and includes configurations for easy deployment.

⁠Quick Start with Docker Hub

Pull and run the latest image directly from Docker Hub:

# Pull the latest image
docker pull dog830228/mcp_weather_server:latest

# Run in stdio mode (default)
docker run dog830228/mcp_weather_server:latest

# Run in SSE mode on port 8080
docker run -p 8080:8080 dog830228/mcp_weather_server:latest --mode sse

# Run in streamable-http mode on port 8080
docker run -p 8080:8080 dog830228/mcp_weather_server:latest --mode streamable-http

# Pull a specific version
docker pull dog830228/mcp_weather_server:0.5.0
docker run -p 8080:8080 dog830228/mcp_weather_server:0.5.0 --mode sse

⁠Available Docker Images

• Latest: dog830228/mcp_weather_server:latest
• Versioned: dog830228/mcp_weather_server:<version> (e.g., 0.5.0)

Images are automatically built and published when new versions are released.