Weather MCP Server

Fornece informações meteorológicas usando a API gratuita e de código aberto Open-Meteo. Nenhuma chave de API necessária.

GitHub

Experimente este MCPPatrocinado

Documentação

Weather MCP Server

mcp-name: io.github.isdaniel/mcp_weather_server

Um servidor Model Context Protocol (MCP) que fornece informações meteorológicas usando a API Open-Meteo. Este servidor suporta múltiplos modos de transporte: stdio padrão, HTTP Server-Sent Events (SSE) e o novo protocolo Streamable HTTP para integração baseada na web.

Recursos

Clima e Qualidade do Ar

Obtenha informações meteorológicas atuais com métricas abrangentes:
- Temperatura, umidade, ponto de orvalho
- Velocidade do vento, direção e rajadas
- Precipitação (chuva/neve) e probabilidade
- Pressão atmosférica e cobertura de nuvens
- Índice UV e visibilidade
- "Sensação térmica"
- Horários do nascer e pôr do sol (hora local no local)
Obtenha dados meteorológicos para um intervalo de datas com detalhes horários e horários diários de nascer/pôr do sol
Obtenha informações de qualidade do ar, incluindo:
- Material particulado PM2.5 e PM10
- Ozônio, dióxido de nitrogênio, monóxido de carbono
- Dióxido de enxofre, amônia, poeira
- Profundidade óptica de aerossóis
- Recomendações e alertas de saúde

Hora e Fuso Horário

Obtenha data/hora atual em qualquer fuso horário
Converta hora entre fusos horários
Obtenha informações de fuso horário

Modos de Transporte

Múltiplos modos de transporte:
- stdio - MCP padrão para clientes desktop (Claude Desktop, etc.)
- SSE - Server-Sent Events para aplicações web
- streamable-http - Protocolo MCP Streamable HTTP moderno com opções com estado/sem estado
Endpoints de API RESTful via integração Starlette

Instalação

Instalando via Smithery

Para instalar o Weather MCP Server automaticamente via Smithery:

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

Instalação Padrão (para clientes MCP como Claude Desktop)

Este pacote pode ser instalado usando pip:

pip install mcp_weather_server

Configuração Manual para Clientes MCP

Este servidor foi projetado para ser instalado manualmente adicionando sua configuração ao arquivo cline_mcp_settings.json.

Adicione a seguinte entrada ao objeto mcpServers no seu arquivo cline_mcp_settings.json:

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

Salve o arquivo cline_mcp_settings.json.

Instalação do Servidor HTTP (para aplicações web)

Para suporte a HTTP SSE ou Streamable HTTP, você precisará de dependências adicionais:

pip install mcp_weather_server starlette uvicorn

Modos de Servidor

Este servidor MCP suporta os modos stdio, SSE e streamable-http em um único servidor unificado:

Comparação de Modos

Recurso	stdio	SSE	streamable-http
Caso de Uso	Clientes MCP desktop	Aplicações web (legado)	Aplicações web (modernas)
Protocolo	Fluxos de I/O padrão	Server-Sent Events	MCP Streamable HTTP
Gerenciamento de Sessão	N/A	Com estado	Com estado ou sem estado
Endpoints	N/A	`/sse`, `/messages/`	`/mcp` (único)
Melhor para	Claude Desktop, Cline	Aplicativos baseados em navegador	Aplicativos web modernos, APIs
Opções de Estado	N/A	Somente com estado	Com estado ou sem estado

1. Modo MCP Padrão (Padrão)

O modo padrão comunica via stdio e é compatível com 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 (Aplicações Web)

O modo SSE executa um servidor HTTP que fornece funcionalidade MCP via Server-Sent Events, tornando-o acessível a aplicações 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 comunicação MCP
POST /messages/ - Endpoint de mensagens para enviar requisições MCP

3. Modo Streamable HTTP (Protocolo MCP Moderno)

O modo streamable-http implementa o novo protocolo MCP Streamable HTTP com um único endpoint /mcp. Este modo suporta operações com estado (padrão) e sem 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

Recursos do Streamable HTTP:

Modo com estado (padrão): Mantém o estado da sessão entre requisições usando IDs de sessão
Modo sem estado: Cria um novo transporte por requisição, sem rastreamento de sessão
Endpoint único: Toda a comunicação MCP acontece através de /mcp
Protocolo moderno: Implementa a especificação mais recente do MCP Streamable HTTP

Endpoint Streamable HTTP:

POST /mcp - Endpoint único para toda a comunicação MCP (initialize, tools/list, tools/call, etc.)

Opções de Linha de Comando:

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

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

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

Configuração

Este servidor não requer chave de API. Ele usa a API Open-Meteo, que é gratuita e de código aberto.

Uso

Este servidor fornece várias ferramentas para operações relacionadas a clima e hora:

Ferramentas Disponíveis

Ferramentas de Clima

get_current_weather - Obtenha o clima atual de uma cidade com métricas abrangentes
get_weather_by_datetime_range - Obtenha dados meteorológicos para um intervalo de datas com detalhes horários
get_weather_details - Obtenha informações meteorológicas detalhadas como dados JSON estruturados

Ferramentas de Qualidade do Ar

get_air_quality - Obtenha informações de qualidade do ar com níveis de poluentes e conselhos de saúde
get_air_quality_details - Obtenha dados detalhados de qualidade do ar como JSON estruturado

Ferramentas de Hora e Fuso Horário

get_current_datetime - Obtenha a hora atual em qualquer fuso horário
get_timezone_info - Obtenha informações de fuso horário
convert_time - Converta hora entre fusos horários

Detalhes das Ferramentas

`get_current_weather`

Obtém informações meteorológicas atuais abrangentes para uma cidade especificada com métricas aprimoradas.

Parâmetros:

city (string, obrigatório): O nome da cidade (somente nomes em inglês)

Retorna: Dados meteorológicos detalhados, incluindo:

Temperatura e "sensação térmica"
Umidade, ponto de orvalho
Velocidade do vento, direção (como direção da bússola) e rajadas
Detalhes de precipitação (chuva/neve) e probabilidade
Pressão atmosférica e cobertura de nuvens
Índice UV com níveis de alerta
Visibilidade

Exemplo de Resposta:

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`

Obtém informações meteorológicas horárias com métricas abrangentes para uma cidade especificada entre as datas de início e fim.

Parâmetros:

city (string, obrigatório): O nome da cidade (somente nomes em inglês)
start_date (string, obrigatório): Data de início no formato YYYY-MM-DD (ISO 8601)
end_date (string, obrigatório): Data de fim no formato YYYY-MM-DD (ISO 8601)

Retorna: Análise meteorológica abrangente, incluindo:

Dados meteorológicos horários com todas as métricas aprimoradas
Tendências de temperatura (máximas, mínimas, médias)
Padrões e probabilidades de precipitação
Avaliação das condições do vento
Tendências do índice UV
Alertas e recomendações meteorológicas

Exemplo de Resposta:

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

Obtenha informações meteorológicas detalhadas para uma cidade especificada como dados JSON estruturados para uso programático.

Parâmetros:

city (string, obrigatório): O nome da cidade (somente nomes em inglês)

Retorna: Dados JSON brutos com todas as métricas meteorológicas adequados para processamento e análise

`get_air_quality`

Obtenha informações atuais de qualidade do ar para uma cidade especificada com níveis de poluentes e recomendações de saúde.

Parâmetros:

city (string, obrigatório): O nome da cidade (somente nomes em inglês)
variables (array, opcional): Poluentes específicos para recuperar. Opções:
- pm10 - Material particulado ≤10μm
- pm2_5 - Material particulado ≤2.5μm
- carbon_monoxide - Níveis de CO
- nitrogen_dioxide - Níveis de NO2
- ozone - Níveis de O3
- sulphur_dioxide - Níveis de SO2
- ammonia - Níveis de NH3
- dust - Níveis de partículas de poeira
- aerosol_optical_depth - Turbidez atmosférica

Retorna: Relatório abrangente de qualidade do ar, incluindo:

Níveis atuais de poluentes com unidades
Classificação da qualidade do ar (Boa/Moderada/Insalubre/Perigosa)
Recomendações de saúde para a população em geral
Alertas específicos para grupos sensíveis
Comparação com os padrões da OMS e da EPA

Exemplo de Resposta:

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`

Obtenha informações detalhadas de qualidade do ar como dados JSON estruturados para análise programática.

Parâmetros:

city (string, obrigatório): O nome da cidade (somente nomes em inglês)
variables (array, opcional): Poluentes específicos para recuperar (mesmas opções de get_air_quality)

Retorna: Dados JSON brutos com métricas completas de qualidade do ar e dados horários

`get_current_datetime`

Obtém a hora atual em um fuso horário especificado.

Parâmetros:

timezone_name (string, obrigatório): Nome do fuso horário IANA (por exemplo, 'America/New_York', 'Europe/London'). Use UTC se nenhum fuso horário for fornecido.

Retorna: Data e hora atuais no fuso horário especificado

Exemplo:

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

`get_timezone_info`

Obtenha informações sobre um fuso horário específico.

Parâmetros:

timezone_name (string, obrigatório): Nome do fuso horário IANA

Retorna: Detalhes do fuso horário, incluindo offset e informações de horário de verão (DST)

`convert_time`

Converta a hora de um fuso horário para outro.

Parâmetros:

time_str (string, obrigatório): Hora a converter (formato ISO)
from_timezone (string, obrigatório): Fuso horário de origem
to_timezone (string, obrigatório): Fuso horário de destino

Retorna: Hora convertida no fuso horário de destino

Exemplos de Uso com Clientes MCP

Usando com Claude Desktop ou 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>

Integração Web (Modo SSE)

Ao executar no modo SSE, você pode integrar o servidor meteorológico com aplicações web:

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

Implantação com Docker

O projeto está disponível como uma imagem Docker no Docker Hub e inclui configurações para implantação fácil.

Início Rápido com Docker Hub

Baixe e execute a imagem mais recente diretamente do 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

Imagens Docker Disponíveis

Mais recente: dog830228/mcp_weather_server:latest
Com versão: dog830228/mcp_weather_server:<version> (por exemplo, 0.5.0)

As imagens são automaticamente construídas e publicadas quando novas versões são lançadas.

Construindo a partir do Código Fonte

Se você quiser construir a imagem Docker você mesmo:

Build Padrão

# 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

Build 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

Desenvolvimento

Estrutura do Projeto

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

Executando para Desenvolvimento

Modo MCP Padrão (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

Adicionando Novas Ferramentas

Para adicionar novas ferramentas relacionadas a clima ou hora:

Crie um novo manipulador de ferramenta no arquivo apropriado em tools/
Herde da classe base ToolHandler
Implemente os métodos necessários (get_name, get_description, call)
Registre a ferramenta em server.py

Dependências

Dependências Principais

mcp>=1.0.0 - Implementação do Model Context Protocol
httpx>=0.28.1 - Cliente HTTP para requisições de API
python-dateutil>=2.8.2 - Utilitários de análise de data/hora

Dependências do Servidor SSE

starlette - Framework web ASGI
uvicorn - Servidor ASGI

Dependências de Desenvolvimento

pytest - Framework de testes

Fontes de Dados da API

Este servidor usa APIs gratuitas e de código aberto:

Dados Meteorológicos: Open-Meteo Weather API

Gratuito e de código aberto
Nenhuma chave de API necessária
Fornece previsões meteorológicas precisas
Suporta locais globais
Dados meteorológicos históricos e atuais
Métricas abrangentes (vento, precipitação, UV, visibilidade)

Dados de Qualidade do Ar:

Gratuito e de código aberto
Nenhuma chave de API necessária
Dados de qualidade do ar em tempo real
Múltiplas medições de poluentes (PM2.5, PM10, O3, NO2, CO, SO2)
Cobertura global
Índices de qualidade do ar baseados em saúde

Solução de Problemas

Problemas Comuns

1. Cidade não encontrada

Certifique-se de que os nomes das cidades estejam em inglês
Tente usar o nome completo da cidade ou inclua o país (por exemplo, "Paris, França")
Verifique a ortografia dos nomes das cidades 2. Servidor HTTP não acessível (SSE ou Streamable HTTP)
Verifique se o servidor está rodando no modo correto:
- SSE: python -m mcp_weather_server --mode sse
- Streamable HTTP: python -m mcp_weather_server --mode streamable-http
Verifique as configurações de firewall para a porta especificada
Garanta que todas as dependências estejam instaladas: pip install starlette uvicorn
Verifique o endpoint correto:
- SSE: http://localhost:8080/sse e http://localhost:8080/messages/
- Streamable HTTP: http://localhost:8080/mcp

3. Problemas de conexão com o cliente MCP

Verifique o caminho do Python na configuração do cliente MCP
Verifique se o pacote mcp_weather_server está instalado
Garanta que o ambiente Python tenha as dependências necessárias

4. Erros de formato de data

Use o formato ISO 8601 para datas: YYYY-MM-DD
Garanta que start_date seja anterior a end_date
Verifique se as datas não estão muito distantes no futuro

Respostas de Erro

O servidor retorna mensagens de erro estruturadas:

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