Weather MCP Server

Proporciona información meteorológica utilizando la API gratuita y de código abierto Open-Meteo. No se requiere clave API.

GitHub

Prueba este MCPPatrocinado

Documentación

Weather MCP Server

mcp-name: io.github.isdaniel/mcp_weather_server

Un servidor de Model Context Protocol (MCP) que proporciona información meteorológica mediante la API de Open-Meteo. Este servidor admite múltiples modos de transporte: stdio estándar, HTTP Server-Sent Events (SSE) y el nuevo protocolo Streamable HTTP para integración web.

Características

Clima y Calidad del Aire

Obtén información meteorológica actual con métricas completas:
- Temperatura, humedad, punto de rocío
- Velocidad del viento, dirección y ráfagas
- Precipitación (lluvia/nieve) y probabilidad
- Presión atmosférica y cobertura de nubes
- Índice UV y visibilidad
- Temperatura de "sensación térmica"
- Horas de salida y puesta del sol (hora local de la ubicación)
Obtén datos meteorológicos para un rango de fechas con detalles horarios y horas diarias de salida/puesta del sol
Obtén información sobre la calidad del aire, incluyendo:
- Material particulado PM2.5 y PM10
- Ozono, dióxido de nitrógeno, monóxido de carbono
- Dióxido de azufre, amoníaco, polvo
- Profundidad óptica de aerosoles
- Avisos y recomendaciones de salud

Hora y Zona Horaria

Obtén la fecha/hora actual en cualquier zona horaria
Convierte la hora entre zonas horarias
Obtén información sobre zonas horarias

Modos de Transporte

Múltiples modos de transporte:
- stdio - MCP estándar para clientes de escritorio (Claude Desktop, etc.)
- SSE - Server-Sent Events para aplicaciones web
- streamable-http - Protocolo moderno MCP Streamable HTTP con opciones con/sin estado
Endpoints de API RESTful mediante integración con Starlette

Instalación

Instalación mediante Smithery

Para instalar Weather MCP Server automáticamente mediante Smithery:

npx -y @smithery/cli install @isdaniel/mcp_weather_server

Instalación estándar (para clientes MCP como Claude Desktop)

Este paquete se puede instalar con pip:

pip install mcp_weather_server

Configuración manual para clientes MCP

Este servidor está diseñado para instalarse manualmente añadiendo su configuración al archivo cline_mcp_settings.json.

Añade la siguiente entrada al objeto mcpServers en tu archivo cline_mcp_settings.json:

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": [
        "-m",
        "mcp_weather_server"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Guarda el archivo cline_mcp_settings.json.

Instalación del servidor HTTP (para aplicaciones web)

Para soporte HTTP SSE o Streamable HTTP, necesitarás dependencias adicionales:

pip install mcp_weather_server starlette uvicorn

Modos del Servidor

Este servidor MCP admite los modos stdio, SSE y streamable-http en un único servidor unificado:

Comparación de Modos

Característica	stdio	SSE	streamable-http
Caso de uso	Clientes MCP de escritorio	Aplicaciones web (heredadas)	Aplicaciones web (modernas)
Protocolo	Flujos de E/S estándar	Server-Sent Events	MCP Streamable HTTP
Gestión de sesiones	N/D	Con estado	Con o sin estado
Endpoints	N/D	`/sse`, `/messages/`	`/mcp` (único)
Ideal para	Claude Desktop, Cline	Aplicaciones basadas en navegador	Aplicaciones web modernas, APIs
Opciones de estado	N/D	Solo con estado	Con o sin estado

1. Modo MCP Estándar (Predeterminado)

El modo estándar se comunica mediante stdio y es compatible con clientes MCP como Claude Desktop.

# Default mode (stdio)
python -m mcp_weather_server

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

2. Modo HTTP SSE (Aplicaciones Web)

El modo SSE ejecuta un servidor HTTP que proporciona funcionalidad MCP mediante Server-Sent Events, haciéndolo accesible para aplicaciones web.

# 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

Endpoints SSE:

GET /sse - Endpoint SSE para comunicación MCP
POST /messages/ - Endpoint de mensajes para enviar solicitudes MCP

3. Modo Streamable HTTP (Protocolo MCP Moderno)

El modo streamable-http implementa el nuevo protocolo MCP Streamable HTTP con un único endpoint /mcp. Este modo admite operaciones con estado (predeterminado) y sin estado.

# 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

Características de Streamable HTTP:

Modo con estado (predeterminado): Mantiene el estado de la sesión entre solicitudes mediante ID de sesión
Modo sin estado: Crea un transporte nuevo por solicitud sin seguimiento de sesión
Endpoint único: Toda la comunicación MCP se realiza a través de /mcp
Protocolo moderno: Implementa la especificación más reciente de MCP Streamable HTTP

Endpoint de Streamable HTTP:

POST /mcp - Endpoint único para toda la comunicación MCP (initialize, tools/list, tools/call, etc.)

Opciones de línea de comandos:

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

Ejemplo de uso SSE:

// 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' }
  })
});

Ejemplo de uso Streamable HTTP:

// 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);
}

Configuración

Este servidor no requiere clave de API. Utiliza la API de Open-Meteo, que es gratuita y de código abierto.

Uso

Este servidor proporciona varias herramientas para operaciones relacionadas con el clima y la hora:

Herramientas Disponibles

Herramientas de Clima

get_current_weather - Obtén el clima actual de una ciudad con métricas completas
get_weather_by_datetime_range - Obtén datos meteorológicos para un rango de fechas con detalles horarios
get_weather_details - Obtén información meteorológica detallada como datos JSON estructurados

Herramientas de Calidad del Aire

get_air_quality - Obtén información sobre la calidad del aire con niveles de contaminantes y consejos de salud
get_air_quality_details - Obtén datos detallados de calidad del aire como JSON estructurado

Herramientas de Hora y Zona Horaria

get_current_datetime - Obtén la hora actual en cualquier zona horaria
get_timezone_info - Obtén información sobre zonas horarias
convert_time - Convierte la hora entre zonas horarias

Detalles de las Herramientas

`get_current_weather`

Recupera información meteorológica actual completa de una ciudad especificada con métricas mejoradas.

Parámetros:

city (cadena, obligatorio): El nombre de la ciudad (solo nombres en inglés)

Devuelve: Datos meteorológicos detallados que incluyen:

Temperatura y temperatura de "sensación térmica"
Humedad, punto de rocío
Velocidad del viento, dirección (como dirección de brújula) y ráfagas
Detalles de precipitación (lluvia/nieve) y probabilidad
Presión atmosférica y cobertura de nubes
Índice UV con niveles de advertencia
Visibilidad

Ejemplo de respuesta:

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`

Recupera información meteorológica horaria con métricas completas para una ciudad especificada entre fechas de inicio y fin.

Parámetros:

city (cadena, obligatorio): El nombre de la ciudad (solo nombres en inglés)
start_date (cadena, obligatorio): Fecha de inicio en formato YYYY-MM-DD (ISO 8601)
end_date (cadena, obligatorio): Fecha de fin en formato YYYY-MM-DD (ISO 8601)

Devuelve: Análisis meteorológico completo que incluye:

Datos meteorológicos horarios con todas las métricas mejoradas
Tendencias de temperatura (máximas, mínimas, medias)
Patrones y probabilidades de precipitación
Evaluación de las condiciones del viento
Tendencias del índice UV
Avisos y recomendaciones meteorológicas

Ejemplo de respuesta:

[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`

Obtén información meteorológica detallada de una ciudad especificada como datos JSON estructurados para uso programático.

Parámetros:

city (cadena, obligatorio): El nombre de la ciudad (solo nombres en inglés)

Devuelve: Datos JSON sin procesar con todas las métricas meteorológicas, adecuados para procesamiento y análisis

`get_air_quality`

Obtén información actual sobre la calidad del aire de una ciudad especificada con niveles de contaminantes y avisos de salud.

Parámetros:

city (cadena, obligatorio): El nombre de la ciudad (solo nombres en inglés)
variables (matriz, opcional): Contaminantes específicos a recuperar. Opciones:
- pm10 - Material particulado ≤10μm
- pm2_5 - Material particulado ≤2.5μm
- carbon_monoxide - Niveles de CO
- nitrogen_dioxide - Niveles de NO2
- ozone - Niveles de O3
- sulphur_dioxide - Niveles de SO2
- ammonia - Niveles de NH3
- dust - Niveles de partículas de polvo
- aerosol_optical_depth - Turbidez atmosférica

Devuelve: Informe completo de calidad del aire que incluye:

Niveles actuales de contaminantes con unidades
Clasificación de la calidad del aire (Buena/Moderada/No saludable/Peligrosa)
Recomendaciones de salud para la población general
Advertencias específicas para grupos sensibles
Comparación con los estándares de la OMS y la EPA

Ejemplo de respuesta:

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`

Obtén información detallada sobre la calidad del aire como datos JSON estructurados para análisis programático.

Parámetros:

city (cadena, obligatorio): El nombre de la ciudad (solo nombres en inglés)
variables (matriz, opcional): Contaminantes específicos a recuperar (mismas opciones que get_air_quality)

Devuelve: Datos JSON sin procesar con métricas completas de calidad del aire y datos horarios

`get_current_datetime`

Recupera la hora actual en una zona horaria especificada.

Parámetros:

timezone_name (cadena, obligatorio): Nombre de zona horaria IANA (p. ej., 'America/New_York', 'Europe/London'). Usa UTC si no se proporciona zona horaria.

Devuelve: Fecha y hora actuales en la zona horaria especificada

Ejemplo:

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

`get_timezone_info`

Obtén información sobre una zona horaria específica.

Parámetros:

timezone_name (cadena, obligatorio): Nombre de zona horaria IANA

Devuelve: Detalles de la zona horaria, incluido el desfase y la información sobre el horario de verano

`convert_time`

Convierte la hora de una zona horaria a otra.

Parámetros:

time_str (cadena, obligatorio): Hora a convertir (formato ISO)
from_timezone (cadena, obligatorio): Zona horaria de origen
to_timezone (cadena, obligatorio): Zona horaria de destino

Devuelve: Hora convertida en la zona horaria de destino

Ejemplos de Uso con Clientes MCP

Uso con Claude Desktop o clientes MCP

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_current_weather</tool_name>
<arguments>
{
  "city": "Tokyo"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_weather_by_datetime_range</tool_name>
<arguments>
{
  "city": "Paris",
  "start_date": "2024-01-01",
  "end_date": "2024-01-07"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_current_datetime</tool_name>
<arguments>
{
  "timezone_name": "Europe/Paris"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_air_quality</tool_name>
<arguments>
{
  "city": "Beijing"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_air_quality</tool_name>
<arguments>
{
  "city": "Los Angeles",
  "variables": ["pm2_5", "pm10", "ozone"]
}
</arguments>
</use_mcp_tool>

Integración Web (Modo SSE)

Cuando se ejecuta en modo SSE, puedes integrar el servidor meteorológico con aplicaciones web:

Ejemplo HTML/JavaScript

<!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>

Implementación con Docker

El proyecto está disponible como imagen de Docker en Docker Hub e incluye configuraciones para una implementación sencilla.

Inicio rápido con Docker Hub

Extrae y ejecuta la imagen más reciente directamente desde 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

Imágenes de Docker disponibles

Última: dog830228/mcp_weather_server:latest
Con versión: dog830228/mcp_weather_server:<version> (p. ej., 0.5.0)

Las imágenes se compilan y publican automáticamente cuando se publican nuevas versiones.

Compilación desde el código fuente

Si quieres compilar la imagen de Docker tú mismo:

Compilación estándar

# Build
docker build -t mcp-weather-server:sse .

# Run (port will be read from PORT env var, defaults to 8081)
docker run -p 8081:8081 mcp-weather-server:sse

# Run with custom port
docker run -p 8080:8080 mcp-weather-server:local --mode sse

Compilación Streamable HTTP

# Build using streamable-http Dockerfile
docker build -f Dockerfile.streamable-http -t mcp-weather-server:streamable-http .

# Run in stateful mode
docker run -p 8080:8080 mcp-weather-server:streamable-http

# Run in stateless mode
docker run -p 8080:8080 -e STATELESS=true mcp-weather-server:streamable-http

Desarrollo

Estructura del proyecto

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

Ejecución para desarrollo

Modo MCP estándar (stdio)

# From project root
python -m mcp_weather_server

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

Modo servidor SSE

# 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

Modo Streamable HTTP

# 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

Añadir nuevas herramientas

Para añadir nuevas herramientas relacionadas con el clima o la hora:

Crea un nuevo controlador de herramienta en el archivo correspondiente dentro de tools/
Hereda de la clase base ToolHandler
Implementa los métodos requeridos (get_name, get_description, call)
Registra la herramienta en server.py

Dependencias

Dependencias principales

mcp>=1.0.0 - Implementación de Model Context Protocol
httpx>=0.28.1 - Cliente HTTP para solicitudes de API
python-dateutil>=2.8.2 - Utilidades de análisis de fecha/hora

Dependencias del servidor SSE

starlette - Marco web ASGI
uvicorn - Servidor ASGI

Dependencias de desarrollo

pytest - Marco de pruebas

Fuentes de Datos de la API

Este servidor utiliza APIs gratuitas y de código abierto:

Datos meteorológicos: API meteorológica de Open-Meteo

Gratuita y de código abierto
No requiere clave de API
Proporciona pronósticos meteorológicos precisos
Admite ubicaciones globales
Datos meteorológicos históricos y actuales
Métricas completas (viento, precipitación, UV, visibilidad)

Datos de calidad del aire:

Gratuitos y de código abierto
No requieren clave de API
Datos de calidad del aire en tiempo real
Mediciones de múltiples contaminantes (PM2.5, PM10, O3, NO2, CO, SO2)
Cobertura global
Índices de calidad del aire basados en la salud

Solución de Problemas

Problemas comunes

1. Ciudad no encontrada

Asegúrate de que los nombres de las ciudades estén en inglés
Prueba a usar el nombre completo de la ciudad o incluye el país (p. ej., "Paris, France")
Comprueba la ortografía de los nombres de las ciudades 2. Servidor HTTP no accesible (SSE o Streamable HTTP)
Verifique que el servidor se esté ejecutando en el modo correcto:
- SSE: python -m mcp_weather_server --mode sse
- Streamable HTTP: python -m mcp_weather_server --mode streamable-http
Compruebe la configuración del firewall para el puerto especificado
Asegúrese de que todas las dependencias estén instaladas: pip install starlette uvicorn
Verifique el endpoint correcto:
- SSE: http://localhost:8080/sse y http://localhost:8080/messages/
- Streamable HTTP: http://localhost:8080/mcp

3. Problemas de conexión del cliente MCP

Verifique la ruta de Python en la configuración del cliente MCP
Compruebe que el paquete mcp_weather_server esté instalado
Asegúrese de que el entorno de Python tenga las dependencias requeridas

4. Errores de formato de fecha

Use el formato ISO 8601 para las fechas: YYYY-MM-DD
Asegúrese de que start_date sea anterior a end_date
Compruebe que las fechas no estén demasiado lejos en el futuro

Respuestas de error

El servidor devuelve mensajes de error estructurados:

{
  "error": "Could not retrieve coordinates for InvalidCity."
}