Labsco
isdaniel logo

Weather MCP Server

โ˜… 51

from isdaniel

Provides weather information using the free and open-source Open-Meteo API. No API key required.

๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅโœ“ VerifiedFreeQuick setup
#automation#devops#git#maps#weather

smithery badge PyPI - Downloads PyPI - Version PyPI Downloads Docker Pulls

<a href="https://glama.ai/mcp/servers/@isdaniel/mcp_weather_server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@isdaniel/mcp_weather_server/badge" /> </a>

Weather MCP Server

mcp-name: io.github.isdaniel/mcp_weather_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

FeaturestdioSSEstreamable-http
Use CaseDesktop MCP clientsWeb applications (legacy)Web applications (modern)
ProtocolStandard I/O streamsServer-Sent EventsMCP Streamable HTTP
Session ManagementN/AStatefulStateful or Stateless
EndpointsN/A/sse, /messages//mcp (single)
Best ForClaude Desktop, ClineBrowser-based appsModern web apps, APIs
State OptionsN/AStateful onlyStateful or Stateless

1. Standard MCP Mode (Default)

The standard mode communicates via stdio and is compatible with MCP clients like Claude Desktop.

Copy & paste โ€” that's it
# Default mode (stdio)
python -m mcp_weather_server

# Explicitly specify stdio mode
python -m mcp_weather_server.server --mode stdio

2. HTTP SSE Mode (Web Applications)

The SSE mode runs an HTTP server that provides MCP functionality via Server-Sent Events, making it accessible to web applications.

Copy & paste โ€” that's it
# Start SSE server on default host/port (0.0.0.0:8080)
python -m mcp_weather_server --mode sse

# Specify custom host and port
python -m mcp_weather_server --mode sse --host localhost --port 3000

# Enable debug mode
python -m mcp_weather_server --mode sse --debug

SSE Endpoints:

  • GET /sse - SSE endpoint for MCP communication
  • POST /messages/ - Message endpoint for sending MCP requests

3. Streamable HTTP Mode (Modern MCP Protocol)

The streamable-http mode implements the new MCP Streamable HTTP protocol with a single /mcp endpoint. This mode supports both stateful (default) and stateless operations.

Copy & paste โ€” that's it
# Start streamable HTTP server on default host/port (0.0.0.0:8080)
python -m mcp_weather_server --mode streamable-http

# Specify custom host and port
python -m mcp_weather_server --mode streamable-http --host localhost --port 3000

# Enable stateless mode (creates fresh transport per request, no session tracking)
python -m mcp_weather_server --mode streamable-http --stateless

# Enable debug mode
python -m mcp_weather_server --mode streamable-http --debug

Streamable HTTP Features:

  • Stateful mode (default): Maintains session state across requests using session IDs
  • Stateless mode: Creates fresh transport per request with no session tracking
  • Single endpoint: All MCP communication happens through /mcp
  • Modern protocol: Implements the latest MCP Streamable HTTP specification

Streamable HTTP Endpoint:

  • POST /mcp - Single endpoint for all MCP communication (initialize, tools/list, tools/call, etc.)

Command Line Options:

Copy & paste โ€” that's it
--mode {stdio,sse,streamable-http}  Server mode: stdio (default), sse, or streamable-http
--host HOST                          Host to bind to (HTTP modes only, default: 0.0.0.0)
--port PORT                          Port to listen on (HTTP modes only, default: 8080)
--stateless                          Run in stateless mode (streamable-http only)
--debug                              Enable debug mode

Example SSE Usage:

Copy & paste โ€” that's it
// Connect to SSE endpoint
const eventSource = new EventSource('http://localhost:8080/sse');

// Send MCP tool request
fetch('http://localhost:8080/messages/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'tool_call',
    tool: 'get_weather',
    arguments: { city: 'Tokyo' }
  })
});

Example Streamable HTTP Usage:

Copy & paste โ€” that's it
// Initialize session and call tool using Streamable HTTP protocol
async function callWeatherTool() {
  const response = await fetch('http://localhost:8080/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'tools/call',
      params: {
        name: 'get_current_weather',
        arguments: { city: 'Tokyo' }
      },
      id: 1
    })
  });

  const result = await response.json();
  console.log(result);
}

Web Integration (SSE Mode)

When running in SSE mode, you can integrate the weather server with web applications:

HTML/JavaScript Example

Copy & paste โ€” that's it
<!DOCTYPE html>
<html>
<head>
    <title>Weather MCP Client</title>
</head>
<body>
    <div id="weather-data"></div>
    <script>
        // Connect to SSE endpoint
        const eventSource = new EventSource('http://localhost:8080/sse');

        eventSource.onmessage = function(event) {
            const data = JSON.parse(event.data);
            document.getElementById('weather-data').innerHTML = JSON.stringify(data, null, 2);
        };

        // Function to get weather
        async function getWeather(city) {
            const response = await fetch('http://localhost:8080/messages/', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    jsonrpc: '2.0',
                    method: 'tools/call',
                    params: {
                        name: 'get_current_weather',
                        arguments: { city: city }
                    },
                    id: 1
                })
            });
        }

        // Example: Get weather for Tokyo
        getWeather('Tokyo');

        // Example: Get air quality
        async function getAirQuality(city) {
            const response = await fetch('http://localhost:8080/messages/', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    jsonrpc: '2.0',
                    method: 'tools/call',
                    params: {
                        name: 'get_air_quality',
                        arguments: { city: city }
                    },
                    id: 2
                })
            });
        }

        getAirQuality('Beijing');
    </script>
</body>
</html>

Development

Project Structure

Copy & paste โ€” that's it
mcp_weather_server/
โ”œโ”€โ”€ src/
โ”‚   โ””โ”€โ”€ mcp_weather_server/
โ”‚       โ”œโ”€โ”€ __init__.py
โ”‚       โ”œโ”€โ”€ __main__.py          # Main MCP server entry point
โ”‚       โ”œโ”€โ”€ server.py            # Unified server (stdio, SSE, streamable-http)
โ”‚       โ”œโ”€โ”€ utils.py             # Utility functions
โ”‚       โ””โ”€โ”€ tools/               # Tool implementations
โ”‚           โ”œโ”€โ”€ __init__.py
โ”‚           โ”œโ”€โ”€ toolhandler.py   # Base tool handler
โ”‚           โ”œโ”€โ”€ tools_weather.py # Weather-related tools
โ”‚           โ”œโ”€โ”€ tools_time.py    # Time-related tools
โ”‚           โ”œโ”€โ”€ tools_air_quality.py # Air quality tools
โ”‚           โ”œโ”€โ”€ weather_service.py   # Weather API service
โ”‚           โ””โ”€โ”€ air_quality_service.py # Air quality API service
โ”œโ”€โ”€ tests/
โ”œโ”€โ”€ Dockerfile                   # Docker configuration for SSE mode
โ”œโ”€โ”€ Dockerfile.streamable-http   # Docker configuration for streamable-http mode
โ”œโ”€โ”€ pyproject.toml
โ”œโ”€โ”€ requirements.txt
โ””โ”€โ”€ README.md

Running for Development

Standard MCP Mode (stdio)

Copy & paste โ€” that's it
# From project root
python -m mcp_weather_server

# Or with PYTHONPATH
export PYTHONPATH="/path/to/mcp_weather_server/src"
python -m mcp_weather_server

SSE Server Mode

Copy & paste โ€” that's it
# From project root
python -m mcp_weather_server --mode sse --host 0.0.0.0 --port 8080

# With custom host/port
python -m mcp_weather_server --mode sse --host localhost --port 3000

Streamable HTTP Mode

Copy & paste โ€” that's it
# Stateful mode (default)
python -m mcp_weather_server --mode streamable-http --host 0.0.0.0 --port 8080

# With debug logging
python -m mcp_weather_server --mode streamable-http --debug

Adding New Tools

To add new weather or time-related tools:

  1. Create a new tool handler in the appropriate file under tools/
  2. Inherit from the ToolHandler base class
  3. Implement the required methods (get_name, get_description, call)
  4. Register the tool in server.py

Dependencies

Core Dependencies

  • mcp>=1.0.0 - Model Context Protocol implementation
  • httpx>=0.28.1 - HTTP client for API requests
  • python-dateutil>=2.8.2 - Date/time parsing utilities

SSE Server Dependencies

  • starlette - ASGI web framework
  • uvicorn - ASGI server

Development Dependencies

  • pytest - Testing framework

API Data Sources

This server uses free and open-source APIs:

Weather Data: Open-Meteo Weather API

  • Free and open-source
  • No API key required
  • Provides accurate weather forecasts
  • Supports global locations
  • Historical and current weather data
  • Comprehensive metrics (wind, precipitation, UV, visibility)

Air Quality Data:

  • Free and open-source
  • No API key required
  • Real-time air quality data
  • Multiple pollutant measurements (PM2.5, PM10, O3, NO2, CO, SO2)
  • Global coverage
  • Health-based air quality indices