MCP 服务器

Weather API MCP Server

yoyooyooo

研究与数据

访问服务器

README

English | 中文

Weather API MCP 服务器

一个用于天气信息的模型上下文协议 (MCP) 服务器实现，使用和风天气 (QWeather) API 提供当前天气数据和预报。

特性

当前天气: 获取任何地点的当前天气数据
天气预报: 获取 3 天到 30 天的天气预报
逐小时预报: 获取 24 小时天气预报
城市查找: 查找城市信息和 ID，以获得更精确的天气数据
可定制选项: 配置单位、语言和其他详细信息
由和风天气驱动: 与和风天气 (QWeather) API 集成，以获取准确的天气数据

安装

npm install mcp-weather-api

或者直接使用 npx：

npx mcp-weather-api

API 参考

天气工具

服务器提供四个可以通过 MCP 调用的天气工具：

1. 获取当前天气

// 工具名称: getWeather
{
  location: "New York, NY",  // 可以是城市名称、坐标（如 "119.98,30.24"）或和风天气位置 ID
  options: {
    units: "metric",        // "metric"（摄氏度）或 "imperial"（华氏度）
    language: "en",         // 语言代码（en、zh 等）
  }
}

2. 获取天气预报

// 工具名称: getWeatherForecast
{
  location: "London, UK",   // 可以是城市名称、坐标（如 "119.98,30.24"）或和风天气位置 ID
  options: {
    units: "imperial",      // "metric"（摄氏度）或 "imperial"（华氏度）
    days: 3,                // 支持 3、7、10、15 或 30 天
    language: "en"          // 语言代码（en、zh 等）
  }
}

3. 获取逐小时天气预报

// 工具名称: getHourlyWeather
{
  location: "Tokyo, Japan", // 可以是城市名称、坐标（如 "119.98,30.24"）或和风天气位置 ID
  options: {
    units: "metric",        // "metric"（摄氏度）或 "imperial"（华氏度）
    hours: 24,              // 小时数（默认：24，最大：24）
    language: "ja"          // 语言代码（en、zh、ja 等）
  }
}

4. 城市查找

// 工具名称: lookupCity
{
  location: "Beijing",      // 城市名称或坐标（如 "119.98,30.24"）
  options: {
    language: "en"          // 语言代码（en、zh 等）
  }
}

天气选项

当前天气工具选项：

interface WeatherOptions {
  units?: "metric" | "imperial"; // 温度单位（默认：metric）
  language?: string; // 响应语言代码
}

预报工具选项：

interface ForecastOptions {
  units?: "metric" | "imperial"; // 温度单位（默认：metric）
  days?: number; // 天数（默认：3）
  language?: string; // 响应语言代码
}

逐小时预报工具选项：

interface HourlyForecastOptions {
  units?: "metric" | "imperial"; // 温度单位（默认：metric）
  hours?: number; // 小时数（默认：24，最大：24）
  language?: string; // 响应语言代码
}

城市查找工具选项：

interface CityLookupOptions {
  language?: string; // 响应语言代码
}

响应格式

所有工具都以以下格式返回响应：

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

示例响应

当前天气响应

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

天气预报响应

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

城市查找响应

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

与 MCP 一起使用

将 Weather MCP 服务器添加到您的 MCP 配置中：

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

和风天气 API

此服务器使用和风天气 (QWeather) API 获取天气数据。 API 密钥包含在软件包中，仅用于演示目的。对于生产用途，您应该从 QWeather 获取自己的 API 密钥。

使用的 API 端点

当前天气 - /weather/now
- 返回当前天气状况
- 响应包括一个包含温度、湿度等的 now 对象。
- API 文档
天气预报 - /weather/3d, /weather/7d, /weather/10d, /weather/15d, /weather/30d
- 返回不同时期的天气预报
- 响应包括一个包含每日预报数据的 daily 数组
- API 文档
逐小时天气预报 - /weather/24h
- 返回未来 24 小时的逐小时天气预报
- 响应包括一个包含逐小时预报数据的 hourly 数组
- API 文档
城市查找 - /city/lookup
- 按名称或坐标查找城市信息
- 返回城市 ID 和其他位置信息
- API 文档

API 响应结构

当前天气 (`/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"
  }
}

天气预报 (`/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...
  ]
}

逐小时天气预报 (`/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...
  ]
}

城市查找 (`/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...
  ]
}

配置

您可以通过环境变量配置各种选项：

# API 配置
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  # 默认位置代码或坐标

# 默认选项
export WEATHER_DEFAULT_UNITS=metric     # 或 'imperial'
export WEATHER_DEFAULT_LANGUAGE=en      # 语言代码
export WEATHER_INCLUDE_DETAILS=true     # 或 'false'
export WEATHER_FORECAST_DAYS=3          # 天数（最多 30 天）

或者在您的 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"
      }
    }
  }
}

位置格式

您可以使用三种格式指定位置：

城市名称: 例如，“New York”、“London”、“Beijing”
坐标: 例如，“119.98,30.24”（经度，纬度）
和风天气位置 ID: 例如，“101010100”（北京）

使用坐标时，格式必须为 longitude,latitude（例如，“119.98,30.24”），它将直接传递给和风天气 API。

使用 lookupCity 工具查找适当的位置 ID 以进行更精确的定位。

中国城市位置代码

对于中国城市，您可以使用和风天气位置 ID，它提供更精确的位置定位。可以在和风天气 LocationList 存储库中找到中国城市代码的完整列表。

此 CSV 文件包含中国城市的位置 ID，格式如下：

开发

前提条件

Node.js 16 或更高版本
npm 或 yarn

设置

克隆存储库
安装依赖项：

npm install

构建

npm run build

在开发中运行

npm run dev