Weather API MCP Server

Proporciona datos meteorológicos actuales y pronósticos utilizando la API de QWeather.

GitHub
1

Documentación

Inglés | 中文

Servidor MCP de Weather API

Una implementación de servidor de Model Context Protocol (MCP) para información meteorológica, que proporciona datos meteorológicos actuales y pronósticos utilizando la API de 和风天气 (QWeather).

Características

  • Clima actual: Obtén datos meteorológicos actuales para cualquier ubicación
  • Pronóstico del tiempo: Obtén pronósticos meteorológicos de 3 a 30 días
  • Pronóstico por horas: Obtén pronósticos meteorológicos de 24 horas
  • Búsqueda de ciudades: Busca información de ciudades e IDs para datos meteorológicos más precisos
  • Opciones personalizables: Configura unidades, idioma y detalles adicionales
  • Impulsado por QWeather: Se integra con la API de 和风天气 (QWeather) para datos meteorológicos precisos

Instalación

npm install mcp-weather-api

O úsalo directamente con npx:

npx mcp-weather-api

Referencia de la API

Herramientas meteorológicas

El servidor proporciona cuatro herramientas meteorológicas que se pueden invocar a través de MCP:

1. Obtener clima actual

// 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. Obtener pronóstico del tiempo

// 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. Obtener pronóstico meteorológico por horas

// 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. Búsqueda de ciudades

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

Opciones meteorológicas

Opciones de la herramienta de clima actual:

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

Opciones de la herramienta de pronóstico:

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

Opciones de la herramienta de pronóstico por horas:

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

Opciones de la herramienta de búsqueda de ciudades:

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

Formato de respuesta

Todas las herramientas devuelven respuestas en el siguiente formato:

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

Respuestas de ejemplo

Respuesta de clima actual

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

Respuesta de pronóstico del tiempo

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

Respuesta de búsqueda de ciudades

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

Agrega el servidor MCP de Weather a tu configuración de MCP:

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

API de QWeather

Este servidor utiliza la API de 和风天气 (QWeather) para obtener datos meteorológicos. La clave de API está incluida en el paquete con fines de demostración. Para uso en producción, debes obtener tu propia clave de API en QWeather.

Endpoints de API utilizados

  1. Clima actual - /weather/now

    • Devuelve las condiciones meteorológicas actuales
    • La respuesta incluye un objeto now con temperatura, humedad, etc.
    • Documentación de la API

  2. Pronóstico del tiempo - /weather/3d, /weather/7d, /weather/10d, /weather/15d, /weather/30d

    • Devuelve el pronóstico meteorológico para diferentes períodos
    • La respuesta incluye un array daily con datos de pronóstico diario
    • Documentación de la API

  3. Pronóstico meteorológico por horas - /weather/24h

    • Devuelve el pronóstico meteorológico por horas para las próximas 24 horas
    • La respuesta incluye un array hourly con datos de pronóstico por horas
    • Documentación de la API

  4. Búsqueda de ciudades - /city/lookup

    • Busca información de ciudades por nombre o coordenadas
    • Devuelve IDs de ciudades y otra información de ubicación
    • Documentación de la API

Estructura de respuesta de la API

Clima actual (/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"
  }
}

Pronóstico del tiempo (/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...
  ]
}

Pronóstico meteorológico por horas (/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...
  ]
}

Búsqueda de ciudades (/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...
  ]
}

Configuración

Puedes configurar varias opciones a través de variables de entorno:

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

O en tu configuración de 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 ubicación

Puedes especificar ubicaciones en tres formatos:

  1. Nombre de ciudad: por ejemplo, "Nueva York", "Londres", "Pekín"
  2. Coordenadas: por ejemplo, "119.98,30.24" (longitud,latitud)
  3. ID de ubicación de QWeather: por ejemplo, "101010100" (Pekín)

Al usar coordenadas, el formato debe ser longitude,latitude (por ejemplo, "119.98,30.24"), que se pasará directamente a la API de QWeather.

Usa la herramienta lookupCity para encontrar el ID de ubicación adecuado para una orientación más precisa.

Códigos de ubicación de ciudades chinas

Para ciudades chinas, puedes usar el ID de ubicación de QWeather que proporciona una orientación de ubicación más precisa. La lista completa de códigos de ciudades chinas se puede encontrar en el repositorio QWeather LocationList.

Este archivo CSV contiene IDs de ubicación para ciudades chinas en el formato:

Desarrollo

Requisitos previos

  • Node.js 16 o superior
  • npm o yarn

Configuración

  1. Clona el repositorio
  2. Instala las dependencias:
npm install

Compilación

npm run build

Ejecución en desarrollo

npm run dev