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 Protocolo de Contexto de Modelo (MCP) que proporciona información meteorológica utilizando la API de Open-Meteo. Este servidor admite múltiples modos de transporte: stdio estándar, Eventos Enviados por el Servidor (SSE) HTTP, y el nuevo protocolo HTTP Streamable para integración web.

Características

Clima y Calidad del Aire

Obtenga 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 "sensación térmica"
- Horas de salida y puesta del sol (hora local en la ubicación)
Obtenga datos meteorológicos para un rango de fechas con detalles horarios y horas diarias de salida/puesta del sol
Obtenga 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

Obtenga la fecha/hora actual en cualquier zona horaria
Convierta la hora entre zonas horarias
Obtenga 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 - Eventos Enviados por el Servidor para aplicaciones web
- streamable-http - Protocolo MCP Streamable HTTP moderno con opciones con estado/sin estado
Puntos finales 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 usando 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ñada la siguiente entrada al objeto mcpServers en su archivo cline_mcp_settings.json:

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

Guarde el archivo cline_mcp_settings.json.

Instalación del servidor HTTP (para aplicaciones web)

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

pip install mcp_weather_server starlette uvicorn

Modos del servidor

Este servidor MCP admite 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	Eventos Enviados por el Servidor	MCP Streamable HTTP
Gestión de sesiones	N/D	Con estado	Con estado o sin estado
Puntos finales	N/D	`/sse`, `/messages/`	`/mcp` (único)
Mejor para	Claude Desktop, Cline	Aplicaciones basadas en navegador	Aplicaciones web modernas, API
Opciones de estado	N/D	Solo con estado	Con estado 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 Eventos Enviados por el Servidor, 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

Puntos finales SSE:

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

3. Modo HTTP Streamable (protocolo MCP moderno)

El modo streamable-http implementa el nuevo protocolo MCP Streamable HTTP con un único punto final /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
Punto final ú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

Punto final de Streamable HTTP:

POST /mcp - Punto final ú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 de 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 una 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 meteorológicas

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

Herramientas de calidad del aire

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

Herramientas de hora y zona horaria

get_current_datetime - Obtenga la hora actual en cualquier zona horaria
get_timezone_info - Obtenga información sobre zonas horarias
convert_time - Convierta la hora entre zonas horarias

Detalles de las herramientas

`get_current_weather`

Recupera información meteorológica actual completa de una ciudad determinada 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 la 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 AAAA-MM-DD (ISO 8601)
end_date (cadena, obligatorio): Fecha de fin en formato AAAA-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
Advertencias 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`

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

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

Obtenga 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'). Use 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`

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

Convierta 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, puede 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

Extraiga y ejecute 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

Más reciente: 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 desea compilar la imagen de Docker usted 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 de 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 de 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:

Cree un nuevo controlador de herramientas en el archivo apropiado bajo tools/
Herede de la clase base ToolHandler
Implemente los métodos requeridos (get_name, get_description, call)
Registre la herramienta en server.py

Dependencias

Dependencias principales

mcp>=1.0.0 - Implementación del Protocolo de Contexto de Modelo
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 API gratuitas y de código abierto:

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

Gratuita y de código abierto
No se 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 se requiere 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úrese de que los nombres de las ciudades estén en inglés
Intente usar el nombre completo de la ciudad o incluya el país (p. ej., "Paris, France")
Verifique la ortografía de los nombres de las ciudades 2. Servidor HTTP no accesible (SSE o Streamable HTTP)
Verifica que el servidor esté ejecutándose en el modo correcto:
- SSE: python -m mcp_weather_server --mode sse
- Streamable HTTP: python -m mcp_weather_server --mode streamable-http
Revisa la configuración del firewall para el puerto especificado
Asegúrate de que todas las dependencias estén instaladas: pip install starlette uvicorn
Verifica 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

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

4. Errores de formato de fecha

Usa el formato ISO 8601 para las fechas: YYYY-MM-DD
Asegúrate de que start_date sea anterior a end_date
Comprueba 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."
}