Open-Meteo

Acesse previsões meteorológicas globais e dados históricos através da API Open-Meteo.

Documentação

Servidor MCP Open-Meteo

Um servidor abrangente de Model Context Protocol (MCP) que fornece acesso às APIs meteorológicas do Open-Meteo para uso com Modelos de Linguagem de Grande Porte.

Recursos

Este servidor MCP fornece acesso completo às APIs do Open-Meteo, incluindo:

APIs Meteorológicas Principais

Previsão do Tempo (weather_forecast) - Previsões de até 16 dias (7 por padrão) com resolução horária e diária
Arquivo Meteorológico (weather_archive) - Dados históricos ERA5 de 1940 até o presente
Qualidade do Ar (air_quality) - PM2.5, PM10, ozônio, dióxido de nitrogênio, pólen, índices de qualidade do ar europeu/americano, índice UV e outros poluentes
Meteorologia Marinha (marine_weather) - Altura das ondas, período das ondas, direção das ondas e temperatura da superfície do mar
Elevação (elevation) - Dados de modelo digital de elevação para coordenadas fornecidas
Geocodificação (geocoding) - Pesquise locais em todo o mundo por nome ou código postal, obtenha coordenadas e informações detalhadas do local

Modelos Meteorológicos Especializados

DWD ICON (dwd_icon_forecast) - Modelo de alta resolução do serviço meteorológico alemão para a Europa
NOAA GFS (gfs_forecast) - Modelo global do serviço meteorológico dos EUA com dados de alta resolução para a América do Norte
Météo-France (meteofrance_forecast) - Modelos AROME e ARPEGE do serviço meteorológico francês
ECMWF (ecmwf_forecast) - Centro Europeu de Previsões Meteorológicas de Médio Prazo
JMA (jma_forecast) - Modelo de alta resolução da Agência Meteorológica do Japão para a Ásia
MET Norway (metno_forecast) - Serviço meteorológico norueguês para países nórdicos
Environment Canada GEM (gem_forecast) - Modelo do serviço meteorológico canadense

Ferramentas Avançadas de Previsão

Previsão de Inundações (flood_forecast) - Vazão de rios e previsões de inundações do GloFAS (Sistema Global de Alerta de Inundações)
Previsão Sazonal (seasonal_forecast) - Previsões de longo prazo de até ~7 meses à frente
Projeções Climáticas (climate_projection) - Projeções de mudanças climáticas CMIP6 para diferentes cenários de aquecimento
Previsão por Conjunto (ensemble_forecast) - Múltiplas execuções de modelos mostrando a incerteza da previsão

Instalação

Requisitos

Node.js >= 22.0.0

Método 1: Usando npx (Recomendado)

Nenhuma instalação necessária! O servidor será executado diretamente via npx.

Método 2: Instalação Global via npm

npm install -g open-meteo-mcp-server

Método 3: A partir do Código-Fonte (Desenvolvimento)

# Clone the repository
git clone https://github.com/cmer81/open-meteo-mcp.git
cd open-meteo-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuração

Configuração do Claude Desktop

Configuração Simples (Recomendada)

Adicione a seguinte configuração ao arquivo de configuração do seu Claude Desktop:

{
  "mcpServers": {
    "open-meteo": {
      "command": "npx",
      "args": ["-y", "-p", "open-meteo-mcp-server", "open-meteo-mcp-server"]
    }
  }
}

Configuração Completa (com variáveis de ambiente)

{
  "mcpServers": {
    "open-meteo": {
      "command": "npx",
      "args": ["-y", "-p", "open-meteo-mcp-server", "open-meteo-mcp-server"],
      "env": {
        "OPEN_METEO_API_URL": "https://api.open-meteo.com",
        "OPEN_METEO_AIR_QUALITY_API_URL": "https://air-quality-api.open-meteo.com",
        "OPEN_METEO_MARINE_API_URL": "https://marine-api.open-meteo.com",
        "OPEN_METEO_ARCHIVE_API_URL": "https://archive-api.open-meteo.com",
        "OPEN_METEO_SEASONAL_API_URL": "https://seasonal-api.open-meteo.com",
        "OPEN_METEO_ENSEMBLE_API_URL": "https://ensemble-api.open-meteo.com",
        "OPEN_METEO_GEOCODING_API_URL": "https://geocoding-api.open-meteo.com",
        "OPEN_METEO_FLOOD_API_URL": "https://flood-api.open-meteo.com",
        "OPEN_METEO_CLIMATE_API_URL": "https://climate-api.open-meteo.com"
      }
    }
  }
}

Configuração de Desenvolvimento Local

Se você está desenvolvendo localmente ou instalou a partir do código-fonte:

{
  "mcpServers": {
    "open-meteo": {
      "command": "node",
      "args": ["/path/to/open-meteo-mcp/dist/index.js"],
      "env": {
        "OPEN_METEO_API_URL": "https://api.open-meteo.com",
        "OPEN_METEO_AIR_QUALITY_API_URL": "https://air-quality-api.open-meteo.com",
        "OPEN_METEO_MARINE_API_URL": "https://marine-api.open-meteo.com",
        "OPEN_METEO_ARCHIVE_API_URL": "https://archive-api.open-meteo.com",
        "OPEN_METEO_SEASONAL_API_URL": "https://seasonal-api.open-meteo.com",
        "OPEN_METEO_ENSEMBLE_API_URL": "https://ensemble-api.open-meteo.com",
        "OPEN_METEO_GEOCODING_API_URL": "https://geocoding-api.open-meteo.com",
        "OPEN_METEO_FLOOD_API_URL": "https://flood-api.open-meteo.com",
        "OPEN_METEO_CLIMATE_API_URL": "https://climate-api.open-meteo.com"
      }
    }
  }
}

Configuração de Instância Personalizada

Se você está usando sua própria instância do Open-Meteo:

{
  "mcpServers": {
    "open-meteo": {
      "command": "npx",
      "args": ["-y", "-p", "open-meteo-mcp-server", "open-meteo-mcp-server"],
      "env": {
        "OPEN_METEO_API_URL": "https://your-meteo-api.example.com",
        "OPEN_METEO_AIR_QUALITY_API_URL": "https://air-quality-api.example.com",
        "OPEN_METEO_MARINE_API_URL": "https://marine-api.example.com",
        "OPEN_METEO_ARCHIVE_API_URL": "https://archive-api.example.com",
        "OPEN_METEO_SEASONAL_API_URL": "https://seasonal-api.example.com",
        "OPEN_METEO_ENSEMBLE_API_URL": "https://ensemble-api.example.com",
        "OPEN_METEO_GEOCODING_API_URL": "https://geocoding-api.example.com",
        "OPEN_METEO_FLOOD_API_URL": "https://flood-api.example.com",
        "OPEN_METEO_CLIMATE_API_URL": "https://climate-api.example.com"
      }
    }
  }
}

Transporte HTTP Streamable

O servidor também suporta transporte HTTP Streamable para implantações remotas. Defina a variável de ambiente TRANSPORT para http:

TRANSPORT=http PORT=3000 npx open-meteo-mcp-server

Isso inicia um servidor Express na porta especificada (padrão: 3000) com o endpoint MCP em /mcp. O transporte HTTP suporta gerenciamento de sessão com IDs de sessão únicos por cliente.

O servidor vincula-se a 127.0.0.1 por padrão, portanto, é acessível apenas a partir da máquina local. Para aceitar conexões de outros hosts, defina HOST=0.0.0.0 explicitamente. A imagem Docker já faz isso, então as portas publicadas funcionam sem configuração extra.

Para implantações de produção, vincule a uma interface acessível e habilite autenticação e limitação de taxa:

HOST=0.0.0.0 API_KEY=your-secret-key RATE_LIMIT_RPM=60 TRANSPORT=http PORT=3000 npx open-meteo-mcp-server

Se um cliente baseado em navegador se conectar ao servidor, liste sua origem em ALLOWED_ORIGINS — solicitações que carregam um cabeçalho Origin não listado são rejeitadas com 403 como proteção contra rebinding de DNS.

Os clientes devem então incluir a chave em cada solicitação:

Authorization: Bearer your-secret-key
# or
X-API-Key: your-secret-key

Usando scripts npm

# Start in HTTP mode (production)
npm run start:http

# Development with auto-reload in HTTP mode
npm run dev:http

Implantação com Docker

O servidor pode ser facilmente implantado usando Docker.

Usando Imagem Pré-construída do GitHub Container Registry (Recomendado)

Baixe e execute a imagem oficial:

# Pull the latest image
docker pull ghcr.io/cmer81/open-meteo-mcp:latest

# Run the container
docker run -d \
  --name open-meteo-mcp \
  -p 3000:3000 \
  ghcr.io/cmer81/open-meteo-mcp:latest

# Check health
curl http://localhost:3000/health

Tags disponíveis (sem prefixo v — a tag git v2.0.0 publica a imagem como 2.0.0):

latest - Última versão estável
2.0.0 - Versão específica
2.0 - Última versão 2.0.x
2 - Última versão 2.x.x

Usando Docker Compose

O repositório inclui duas configurações do Docker Compose:

Produção (usa imagem pré-construída):

# Start with pre-built image from GitHub Container Registry
docker compose up -d

# View logs
docker compose logs -f

# Stop the server
docker compose down

Desenvolvimento (compila a partir do código-fonte):

# Build and start from local source
docker compose -f docker-compose.dev.yml up -d

# Rebuild after code changes
docker compose -f docker-compose.dev.yml up -d --build

Compilando a partir do Código-Fonte

Se você preferir compilar a imagem você mesmo:

# Build the image
npm run docker:build
# or
docker build -t open-meteo-mcp-server .

# Run the container
npm run docker:run
# or
docker run -p 3000:3000 open-meteo-mcp-server

Configuração de Ambiente

Copie .env.example para .env e personalize conforme necessário:

cp .env.example .env
# Edit .env with your configuration

Em seguida, atualize docker-compose.yml para usar o arquivo .env ou passe variáveis de ambiente diretamente.

Verificação de Saúde

O servidor HTTP inclui um endpoint de verificação de saúde:

curl http://localhost:3000/health
# Response: {"status":"ok"}

Este endpoint é usado pelo HEALTHCHECK do Docker e pode ser integrado a plataformas de orquestração de contêineres (Kubernetes, Docker Swarm, etc.).

Variáveis de Ambiente

Todas as variáveis de ambiente são opcionais e possuem padrões sensatos:

OPEN_METEO_API_URL - URL base para a API de previsão do Open-Meteo (padrão: https://api.open-meteo.com)
OPEN_METEO_AIR_QUALITY_API_URL - URL da API de qualidade do ar (padrão: https://air-quality-api.open-meteo.com)
OPEN_METEO_MARINE_API_URL - URL da API meteorológica marinha (padrão: https://marine-api.open-meteo.com)
OPEN_METEO_ARCHIVE_API_URL - URL da API de dados históricos (padrão: https://archive-api.open-meteo.com)
OPEN_METEO_SEASONAL_API_URL - URL da API de previsão sazonal (padrão: https://seasonal-api.open-meteo.com)
OPEN_METEO_ENSEMBLE_API_URL - URL da API de previsão por conjunto (padrão: https://ensemble-api.open-meteo.com)
OPEN_METEO_GEOCODING_API_URL - URL da API de geocodificação (padrão: https://geocoding-api.open-meteo.com)
OPEN_METEO_FLOOD_API_URL - URL da API de previsão de inundações (padrão: https://flood-api.open-meteo.com)
OPEN_METEO_CLIMATE_API_URL - URL da API de projeção climática (padrão: https://climate-api.open-meteo.com)
TRANSPORT - Modo de transporte: http para HTTP Streamable, omita para stdio (padrão: stdio)
PORT - Porta do servidor HTTP ao usar transporte HTTP (padrão: 3000)
HOST - Interface à qual o transporte HTTP se vincula (padrão: 127.0.0.1, somente loopback). Defina como 0.0.0.0 para aceitar conexões de outras máquinas. A imagem Docker já define isso como 0.0.0.0, então as portas publicadas funcionam imediatamente.

Segurança do Transporte HTTP (opcional)

API_KEY - Quando definido, todas as solicitações para /mcp devem incluir esta chave via Authorization: Bearer <key> ou X-API-Key: <key>. Deixe não definido para acesso aberto (modo local/desenvolvimento). Aplicado em GET, POST e DELETE igualmente.
RATE_LIMIT_RPM - Máximo de solicitações por minuto por IP (padrão: 60). Somente transporte HTTP.
TRUSTED_PROXIES - Lista separada por vírgulas de IPs de proxy confiáveis ou intervalos CIDR (ex.: 10.0.0.0/8,172.16.0.0/12). Quando definido, X-Forwarded-For é respeitado apenas para solicitações originadas desses endereços. Deixe não definido para sempre usar o IP da conexão direta.
ALLOWED_ORIGINS - Lista separada por vírgulas de origens de navegadores permitidas para acessar o servidor (ex.: http://localhost:5173,https://app.example). Protege contra rebinding de DNS: qualquer solicitação que carregue um cabeçalho Origin que não esteja listado é rejeitada com 403. Solicitações sem um cabeçalho Origin — clientes CLI e transportes SDK — não são afetadas. Vazio por padrão.

/health permanece acessível sem chave e sem limitação de taxa, para que as sondas de contêineres continuem funcionando.

Habilidades

O diretório skills/ contém arquivos SKILL.md que ajudam assistentes de IA a usar este servidor MCP de forma eficaz. Eles atuam como guias contextuais — a IA lê a habilidade relevante para saber qual ferramenta chamar e como usar seus parâmetros.

Habilidades disponíveis

Habilidade	Arquivo	Melhor para
`open-meteo`	`skills/open-meteo/SKILL.md`	Clima do dia a dia: previsões, dados históricos, qualidade do ar, condições marinhas, elevação
`open-meteo-advanced`	`skills/open-meteo-advanced/SKILL.md`	Modelos específicos (ECMWF, GFS, DWD ICON…), incerteza por conjunto, perspectivas sazonais, projeções climáticas

Usando com Claude Code (CLI)

Copie as habilidade(s) para o diretório de habilidades do seu Claude:

cp -r skills/open-meteo ~/.claude/skills/
cp -r skills/open-meteo-advanced ~/.claude/skills/

Isso as instala em ~/.claude/skills/open-meteo/SKILL.md e ~/.claude/skills/open-meteo-advanced/SKILL.md. O Claude Code carregará a habilidade relevante automaticamente quando você fizer perguntas relacionadas ao clima.

Usando com Claude Desktop

Envie o arquivo SKILL.md diretamente como um documento na sua conversa do Claude Desktop:

Para perguntas sobre o clima do dia a dia: envie skills/open-meteo/SKILL.md
Para seleção de modelos, conjunto ou projeções climáticas: envie skills/open-meteo-advanced/SKILL.md

Envie uma habilidade por conversa. A IA a usará como guia de referência durante toda a sessão.

Exemplos de Uso

Geocodificação e Pesquisa de Localização

Find the coordinates for Paris, France

Search for locations named "Berlin" and return the top 5 results

What are the coordinates for postal code 75001?

Search for "Lyon" in France only (countryCode: FR) with results in French (language: fr)

Find all cities named "London" in the United Kingdom with English descriptions

Previsão Meteorológica Básica

Can you get me the weather forecast for Paris (48.8566, 2.3522) with temperature, humidity, and precipitation for the next 3 days?

Dados Meteorológicos Históricos

What were the temperatures in London during January 2023?

Monitoramento da Qualidade do Ar

What's the current air quality in Beijing with PM2.5 and ozone levels?

Give me the current European AQI, UV index, and pollen levels (birch, grass, ragweed) in Paris.

Meteorologia Marinha

Get me the wave height and sea surface temperature for coordinates 45.0, -125.0 for the next 5 days.

Monitoramento de Inundações

Check the river discharge forecast for coordinates 52.5, 13.4 for the next 30 days.

Previsão Sazonal

Give me the weekly and monthly temperature outlook for Madrid over the next 4 months.

Previsão por Conjunto

Compare the ICON and GFS ensemble forecasts for Berlin over the next 5 days and show the spread across members.

Projeções Climáticas

Show me temperature projections for New York from 2050 to 2070 using CMIP6 models.

Parâmetros da API

Parâmetros Obrigatórios

latitude : Latitude no sistema de coordenadas WGS84 (-90 a 90)
longitude : Longitude no sistema de coordenadas WGS84 (-180 a 180)

Variáveis Meteorológicas Horárias

temperature_2m : Temperatura a 2 metros
relative_humidity_2m : Umidade relativa
precipitation : Precipitação
wind_speed_10m : Velocidade do vento a 10 metros
wind_direction_10m : Direção do vento
pressure_msl : Pressão média ao nível do mar
cloud_cover : Percentual de cobertura de nuvens
weather_code : Código da condição meteorológica
visibility : Visibilidade
uv_index : Índice UV
E muitos outros...

Variáveis Meteorológicas Diárias

temperature_2m_max/min : Temperaturas máxima/mínima
precipitation_sum : Precipitação total
wind_speed_10m_max : Velocidade máxima do vento
sunrise/sunset : Horários do nascer e pôr do sol
weather_code : Código da condição meteorológica
uv_index_max : Índice UV máximo

Variáveis de Qualidade do Ar

pm10 : Partículas PM10
pm2_5 : Partículas PM2.5
carbon_monoxide : Monóxido de carbono
nitrogen_dioxide : Dióxido de nitrogênio
ozone : Ozônio
sulphur_dioxide : Dióxido de enxofre
ammonia : Amônia
dust : Partículas de poeira
alder_pollen : Pólen de amieiro (somente Europa)
birch_pollen : Pólen de bétula (somente Europa)
grass_pollen : Pólen de gramíneas (somente Europa)
mugwort_pollen : Pólen de artemísia (somente Europa)
olive_pollen : Pólen de oliveira (somente Europa)
ragweed_pollen : Pólen de ambrosia (somente Europa)
european_aqi : Índice Europeu de Qualidade do Ar
european_aqi_pm2_5 : IQA Europeu para PM2.5
european_aqi_pm10 : IQA Europeu para PM10
european_aqi_nitrogen_dioxide : IQA Europeu para NO₂
european_aqi_ozone : IQA Europeu para ozônio
european_aqi_sulphur_dioxide : IQA Europeu para SO₂
us_aqi : Índice Americano de Qualidade do Ar
us_aqi_pm2_5 : IQA Americano para PM2.5
us_aqi_pm10 : IQA Americano para PM10
us_aqi_nitrogen_dioxide : IQA Americano para NO₂
us_aqi_ozone : IQA Americano para ozônio
us_aqi_sulphur_dioxide : IQA Americano para SO₂
us_aqi_carbon_monoxide : IQA Americano para CO
uv_index : Índice UV
uv_index_clear_sky : Índice UV em condições de céu limpo

Variáveis Meteorológicas Marinhas

wave_height : Altura das ondas
wave_direction : Direção das ondas
wave_period : Período das ondas
wind_wave_height : Altura das ondas de vento
swell_wave_height : Altura das ondas de swell
sea_surface_temperature : Temperatura da superfície do mar

Opções de Formatação

temperature_unit : celsius, fahrenheit
wind_speed_unit : kmh, ms, mph, kn
precipitation_unit : mm, inch
timezone : Europe/Paris, America/New_York, etc.

Opções de Intervalo de Tempo

forecast_days : Número de dias de previsão (varia por API)
past_days : Incluir dados de dias anteriores
start_date / end_date : Intervalo de datas para dados históricos (formato YYYY-MM-DD)

Scripts de Desenvolvimento

# Development with auto-reload
npm run dev

# Build TypeScript
npm run build

# Start production server
npm start

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

Avaliações

O diretório evals/ contém um benchmark de usabilidade para LLM das ferramentas deste servidor — uma verificação diferente do npm test. Os testes unitários verificam se o código está correto; isto verifica se um LLM com apenas as ferramentas deste servidor (sem outro contexto) consegue realmente concluir tarefas realistas com elas.

evals/evaluation.xml — 10 pares independentes de pergunta/resposta somente leitura, construídos sobre dados históricos estáveis (arquivo ERA5, projeções CMIP6, geocodificação, elevação), para que as respostas esperadas nunca mudem ao longo do tempo.
evals/scripts/evaluation.py — harness que inicia o servidor, permite que um agente responda a cada pergunta usando apenas suas ferramentas e compara a resposta com a esperada.

Executando a avaliação

npm run build
pip install -r evals/scripts/requirements.txt
export ANTHROPIC_API_KEY=your_api_key_here

npm run eval
# or directly:
python3 evals/scripts/evaluation.py -t stdio -c node -a dist/index.js evals/evaluation.xml

Isso chama a API real da Anthropic para cada pergunta, portanto consome tokens/créditos — é uma verificação manual de qualidade para o design das ferramentas, não faz parte do CI.

Ao adicionar, remover ou renomear uma ferramenta, ou alterar materialmente a descrição ou o esquema de uma ferramenta, considere adicionar ou atualizar um qa_pair em evals/evaluation.xml que a exercite.

Estrutura do Projeto

src/
├── index.ts          # MCP server entry point
├── client.ts         # HTTP client for Open-Meteo API
├── tools.ts          # MCP tool definitions
├── types.ts          # Zod validation schemas
├── truncation.ts     # Response size capping and serialization
└── security.ts       # Auth, origin validation, rate limiter, IP extraction

Cobertura da API

Este servidor fornece acesso a todos os principais endpoints do Open-Meteo:

Dados Meteorológicos

Condições meteorológicas atuais
Previsões horárias (até 16 dias)
Previsões diárias (até 16 dias)
Dados meteorológicos históricos (1940-presente)

Modelos Especializados

Modelos regionais de alta resolução (DWD ICON, Météo-France AROME)
Modelos globais (NOAA GFS, ECMWF)
Especialistas regionais (JMA para a Ásia, MET Norway para os países nórdicos)

Dados Ambientais

Previsões de qualidade do ar
Condições marinhas e oceânicas
Vazão de rios e alertas de enchentes
Projeções de mudanças climáticas

Recursos Avançados

Previsões de conjunto (ensemble) para quantificação de incertezas
Previsões sazonais para planejamento de longo prazo
Comparação de múltiplos modelos
Unidades e fusos horários personalizáveis

Tratamento de Erros

O servidor fornece tratamento abrangente de erros com mensagens de erro detalhadas para:

Coordenadas inválidas
Parâmetros obrigatórios ausentes
Limites de taxa da API
Problemas de conectividade de rede
Intervalos de datas inválidos

Limites de Tamanho de Resposta

As respostas das ferramentas são limitadas a 25.000 caracteres para que uma única consulta ampla não estoure o contexto de um LLM. Quando uma resposta excede o limite, os arrays de séries temporais (hourly, daily, minutely_15) são reduzidos por uma proporção igual — mantendo todas as séries paralelas alinhadas nos mesmos timestamps — e dois campos são adicionados:

{
  "truncated": true,
  "truncation_message": "Response truncated from 95538 characters to stay within the 25000-character limit. Narrow the request (start_date/end_date, forecast_days, past_days, or fewer variables) to retrieve the full data."
}

Para obter dados completos, restrinja a solicitação: intervalo de datas mais curto, menos forecast_days/past_days ou menos variáveis.

Desempenho

Cliente HTTP eficiente com pooling de conexões
Serialização de dados otimizada
Pegada de memória mínima

Documentação da API

Para documentação detalhada da API, consulte o arquivo openapi.yml e a documentação da API do Open-Meteo.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Configuração de Desenvolvimento

Faça um fork do repositório
Clone seu fork: git clone https://github.com/your-username/open-meteo-mcp.git
Instale as dependências: npm install
Crie um branch de feature: git checkout -b feature/amazing-feature
Faça suas alterações e adicione testes
Execute os testes: npm test
Faça commit das suas alterações: git commit -m 'Add amazing feature'
Envie para o branch: git push origin feature/amazing-feature
Abra um Pull Request

Lançamentos

Este projeto usa lançamentos automatizados via GitHub Actions. Para criar um novo lançamento:

# For a patch release (1.0.0 -> 1.0.1)
npm run release:patch

# For a minor release (1.0.0 -> 1.1.0)
npm run release:minor

# For a major release (1.0.0 -> 2.0.0)
npm run release:major

A GitHub Action automaticamente:

Executará os testes e compilará o projeto
Publicará no npm com proveniência
Criará um lançamento no GitHub
Atualizará os selos de versão

Licença

MIT