Weather API MCP Server

Fornece dados meteorológicos atuais e previsões usando a API QWeather.

GitHub
1
Experimente este MCPPatrocinado

Documentação

English | 中文

Weather API MCP Server

Uma implementação de servidor Model Context Protocol (MCP) para informações meteorológicas, fornecendo dados meteorológicos atuais e previsões usando a API 和风天气 (QWeather).

Recursos

  • Clima Atual: Obtenha dados meteorológicos atuais para qualquer local
  • Previsão do Tempo: Obtenha previsões do tempo de 3 a 30 dias
  • Previsão Horária: Obtenha previsões meteorológicas de 24 horas
  • Busca de Cidades: Consulte informações e IDs de cidades para dados meteorológicos mais precisos
  • Opções Personalizáveis: Configure unidades, idioma e detalhes adicionais
  • Alimentado por QWeather: Integra-se à API 和风天气 (QWeather) para dados meteorológicos precisos

Instalação

npm install mcp-weather-api

Ou use diretamente com npx:

npx mcp-weather-api

Referência da API

Ferramentas Meteorológicas

O servidor fornece quatro ferramentas meteorológicas que podem ser chamadas via MCP:

1. Obter Clima Atual

// Tool name: getWeather
{
  location: "New York, NY",  // Can be city name, coordinates like "119.98,30.24", or QWeather location ID
  options: {
    units: "metric",        // "metric" (Celsius) or "imperial" (Fahrenheit)
    language: "en",         // Language code (en, zh, etc.)
  }
}

2. Obter Previsão do Tempo

// Tool name: getWeatherForecast
{
  location: "London, UK",   // Can be city name, coordinates like "119.98,30.24", or QWeather location ID
  options: {
    units: "imperial",      // "metric" (Celsius) or "imperial" (Fahrenheit)
    days: 3,                // Supports 3, 7, 10, 15, or 30 days
    language: "en"          // Language code (en, zh, etc.)
  }
}

3. Obter Previsão Meteorológica Horária

// Tool name: getHourlyWeather
{
  location: "Tokyo, Japan", // Can be city name, coordinates like "119.98,30.24", or QWeather location ID
  options: {
    units: "metric",        // "metric" (Celsius) or "imperial" (Fahrenheit)
    hours: 24,              // Number of hours (default: 24, max: 24)
    language: "ja"          // Language code (en, zh, ja, etc.)
  }
}

4. Busca de Cidades

// Tool name: lookupCity
{
  location: "Beijing",      // City name or coordinates like "119.98,30.24"
  options: {
    language: "en"          // Language code (en, zh, etc.)
  }
}

Opções Meteorológicas

Opções da ferramenta de clima atual:

interface WeatherOptions {
  units?: "metric" | "imperial"; // Temperature units (default: metric)
  language?: string; // Response language code
}

Opções da ferramenta de previsão:

interface ForecastOptions {
  units?: "metric" | "imperial"; // Temperature units (default: metric)
  days?: number; // Number of days (default: 3)
  language?: string; // Response language code
}

Opções da ferramenta de previsão horária:

interface HourlyForecastOptions {
  units?: "metric" | "imperial"; // Temperature units (default: metric)
  hours?: number; // Number of hours (default: 24, max: 24)
  language?: string; // Response language code
}

Opções da ferramenta de busca de cidades:

interface CityLookupOptions {
  language?: string; // Response language code
}

Formato de Resposta

Todas as ferramentas retornam respostas no seguinte formato:

{
  content: Array<{
    type: "text";
    text: string;
  }>;
}

Exemplos de Respostas

Resposta de Clima Atual

Weather for New York:

Observation Time: 2023-11-15T12:30+08:00
Current Conditions: Partly Cloudy (Icon: 101)
Temperature: 18.5°C
Feels Like: 19.2°C

Wind Information:
- Direction: Northeast (45°)
- Scale: 3
- Speed: 15 km/h

Other Information:
- Humidity: 65%
- Precipitation: 0.0 mm
- Pressure: 1013 hPa
- Visibility: 25 km
- Cloud Cover: 30%
- Dew Point: 12.1°C

Updated: 2023-11-15T12:35+08:00

Data Sources: QWeather
License: QWeather Developers License

Resposta de Previsão do Tempo

Weather Forecast for London:

2023-11-15:
Time Information:
- Sunrise: 07:12, Sunset: 16:30
- Moonrise: 15:40, Moonset: 03:25
- Moon Phase: Waxing Gibbous (Icon: 802)

Day Weather:
- Conditions: Rain (Icon: 305)
- Temperature Range: 12.0°F / 7.0°F
- Wind: Northwest (315°)
- Wind Scale: 3, Speed: 18 km/h

Night Weather:
- Conditions: Cloudy (Icon: 101)
- Wind: North (0°)
- Wind Scale: 2, Speed: 10 km/h

Other Information:
- Humidity: 75%
- Precipitation: 5.2 mm
- Pressure: 1008 hPa
- Visibility: 10 km
- Cloud Cover: 85%
- UV Index: 2

...additional days...

Data Sources: QWeather
License: QWeather Developers License

Resposta de Busca de Cidades

Location Information:

1. Beijing (ID: 101010100)
   Location: 39.90499, 116.40529
   Region: Beijing, Beijing, China
   Timezone: Asia/Shanghai (UTC +8.0)
   Type: city, Rank: 10

2. Beijing Shi (ID: 101010000)
   Location: 39.90998, 116.40529
   Region: Beijing, Beijing, China
   Timezone: Asia/Shanghai (UTC +8.0)
   Type: city, Rank: 10

Note: Use the ID (e.g., "101010100") in other weather tools to get weather information for this location.

Data Sources: QWeather
License: QWeather Developers License

Uso com MCP

Adicione o servidor Weather MCP à sua configuração MCP:

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "mcp-weather-api"]
    }
  }
}

API QWeather

Este servidor usa a API 和风天气 (QWeather) para buscar dados meteorológicos. A chave da API está incluída no pacote para fins de demonstração. Para uso em produção, você deve obter sua própria chave de API em QWeather.

Endpoints da API Utilizados

  1. Clima Atual - /weather/now

    • Retorna as condições meteorológicas atuais
    • A resposta inclui um objeto now com temperatura, umidade, etc.
    • Documentação da API

  2. Previsão do Tempo - /weather/3d, /weather/7d, /weather/10d, /weather/15d, /weather/30d

    • Retorna a previsão do tempo para diferentes períodos
    • A resposta inclui um array daily com dados de previsão diária
    • Documentação da API

  3. Previsão Meteorológica Horária - /weather/24h

    • Retorna a previsão meteorológica horária para as próximas 24 horas
    • A resposta inclui um array hourly com dados de previsão horária
    • Documentação da API

  4. Busca de Cidades - /city/lookup

    • Busca informações de cidades por nome ou coordenadas
    • Retorna IDs de cidades e outras informações de localização
    • Documentação da API

Estrutura de Resposta da API

Clima Atual (/weather/now)

{
  "code": "200",
  "updateTime": "2021-11-15T16:35+08:00",
  "now": {
    "temp": "22.5",
    "humidity": "65",
    "text": "Partly cloudy",
    "windSpeed": "10.2",
    "windDir": "East",
    "feelsLike": "24.0",
    "pressure": "1012",
    "vis": "10",
    "cloud": "30",
    "dew": "15.5"
  }
}

Previsão do Tempo (/weather/3d)

{
  "code": "200",
  "updateTime": "2021-11-15T16:35+08:00",
  "fxLink": "http://hfx.link/2ax1",
  "daily": [
    {
      "fxDate": "2021-11-15",
      "sunrise": "06:58",
      "sunset": "16:59",
      "moonrise": "15:16",
      "moonset": "03:40",
      "moonPhase": "盈凸月",
      "moonPhaseIcon": "803",
      "tempMax": "12",
      "tempMin": "-1",
      "iconDay": "101",
      "textDay": "多云",
      "iconNight": "150",
      "textNight": "晴",
      "wind360Day": "45",
      "windDirDay": "东北风",
      "windScaleDay": "1-2",
      "windSpeedDay": "3",
      "wind360Night": "0",
      "windDirNight": "北风",
      "windScaleNight": "1-2",
      "windSpeedNight": "3",
      "humidity": "65",
      "precip": "0.0",
      "pressure": "1020",
      "vis": "25",
      "cloud": "4",
      "uvIndex": "3"
    }
    // Additional days...
  ]
}

Previsão Meteorológica Horária (/weather/24h)

{
  "code": "200",
  "updateTime": "2021-11-15T16:35+08:00",
  "fxLink": "http://hfx.link/2ax1",
  "hourly": [
    {
      "fxTime": "2021-11-15T17:00+08:00",
      "temp": "11",
      "icon": "150",
      "text": "晴",
      "wind360": "335",
      "windDir": "西北风",
      "windScale": "3-4",
      "windSpeed": "20",
      "humidity": "73",
      "pop": "7",
      "precip": "0.0",
      "pressure": "1013",
      "cloud": "10",
      "dew": "7"
    }
    // Additional hours...
  ]
}

Busca de Cidades (/city/lookup)

{
  "code": "200",
  "location": [
    {
      "name": "Beijing",
      "id": "101010100",
      "lat": "39.90499",
      "lon": "116.40529",
      "adm2": "Beijing",
      "adm1": "Beijing",
      "country": "China",
      "tz": "Asia/Shanghai",
      "utcOffset": "+08:00",
      "isDst": "0",
      "type": "city",
      "rank": "10",
      "fxLink": "http://hfx.link/2ax1"
    }
    // Additional locations...
  ]
}

Configuração

Você pode configurar várias opções por meio de variáveis de ambiente:

# API Configuration
export QWEATHER_API_KEY=your-api-key
export QWEATHER_API_URL=https://devapi.qweather.com/v7
export QWEATHER_GEO_API_URL=https://geoapi.qweather.com/v2
export WEATHER_DEFAULT_LOCATION=101010100  # Default location code or coordinates

# Default Options
export WEATHER_DEFAULT_UNITS=metric     # or 'imperial'
export WEATHER_DEFAULT_LANGUAGE=en      # language code
export WEATHER_INCLUDE_DETAILS=true     # or 'false'
export WEATHER_FORECAST_DAYS=3          # number of days (max 30)

Ou na sua configuração MCP:

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "mcp-weather-api"],
      "env": {
        "QWEATHER_API_KEY": "your-api-key",
        "QWEATHER_API_URL": "https://devapi.qweather.com/v7",
        "QWEATHER_GEO_API_URL": "https://geoapi.qweather.com/v2",
        "WEATHER_DEFAULT_LOCATION": "101010100",
        "WEATHER_DEFAULT_UNITS": "imperial",
        "WEATHER_DEFAULT_LANGUAGE": "zh",
        "WEATHER_INCLUDE_DETAILS": "true",
        "WEATHER_FORECAST_DAYS": "7"
      }
    }
  }
}

Formatos de Localização

Você pode especificar locais em três formatos:

  1. Nome da cidade: ex.: "Nova York", "Londres", "Pequim"
  2. Coordenadas: ex.: "119.98,30.24" (longitude,latitude)
  3. ID de localização QWeather: ex.: "101010100" (Pequim)

Ao usar coordenadas, o formato deve ser longitude,latitude (ex.: "119.98,30.24"), que será passado diretamente para a API QWeather.

Use a ferramenta lookupCity para encontrar o ID de localização apropriado para um direcionamento mais preciso.

Códigos de Localização de Cidades Chinesas

Para cidades chinesas, você pode usar o ID de localização QWeather, que fornece um direcionamento de localização mais preciso. A lista completa de códigos de cidades chinesas pode ser encontrada no repositório QWeather LocationList.

Este arquivo CSV contém IDs de localização para cidades chinesas no formato:

Desenvolvimento

Pré-requisitos

  • Node.js 16 ou superior
  • npm ou yarn

Configuração

  1. Clone o repositório
  2. Instale as dependências:
npm install

Compilação

npm run build

Executando em Desenvolvimento

npm run dev