Openweathermcp

OpenWeatherMap MCP 服务

English | 中文

基于模型上下文协议（MCP）的 OpenWeatherMap API 综合集成服务，为 AI 助手提供全面的天气数据访问能力。

🌟 主要功能

核心天气功能

• 🌡️ 实时天气查询 - 提供温度、湿度、风速、气压等实时天气数据
• 📅 天气预报 - 提供 5 天、每 3 小时间隔的详细天气预报及趋势分析
• 🏭 空气质量监测 - 提供实时空气质量指数和污染物浓度数据
• 🗺️ 天气地图 - 提供多图层天气地图瓦片（云层、降水、温度等）
• ⚠️ 天气预警 - 提供政府发布的天气警报和安全提示
• 📊 历史天气 - 支持查询历史天气数据并进行多日对比分析

智能城市名称查询

• 🧠 智能回退 - 自动处理中文和英文城市名称
• 🔄 自动地理编码 - 直接查询城市名称失败时，自动通过地理编码获取坐标
• 🌍 通用支持 - 通过地理编码 API 支持任何语言的城市名称

其他功能

• 🌍 地理编码 - 将地点名称转换为坐标，并支持模糊搜索
• 📍 反向地理编码 - 将坐标转换为地点名称
• 🔄 多单位支持 - 支持公制、英制和标准单位制
• 🌐 多语言支持 - 支持中文、英文及多种其他语言

📦 安装

前置条件

• Node.js 18.0.0 或更高版本
• OpenWeatherMap API 密钥

获取 API 密钥

1. 访问 OpenWeatherMap
2. 注册账户并获取免费 API 密钥
3. 设置环境变量：

   export OPENWEATHER_API_KEY="your_api_key_here"
   

安装方式

方式 1：全局安装 NPM

npm install -g openweather-mcp

方式 2：从源代码构建

git clone https://github.com/QianJue-CN/OpenWeatherMCP.git
cd OpenWeatherMCP
npm install
npm run build

🚀 使用

作为 MCP 服务运行

# Set API key
export OPENWEATHER_API_KEY="your_api_key_here"

# Start server
npx openweather-mcp

在 Claude Desktop 中配置

添加到 Claude Desktop 配置文件：

{
  "mcpServers": {
    "openweather": {
      "command": "npx",
      "args": ["openweather-mcp"],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

与其他 MCP 客户端搭配使用

任何兼容 MCP 协议的客户端都可以连接到此服务。

🛠️ 可用工具

1. 实时天气查询（get_current_weather）

获取指定位置的实时天气信息。

参数：

• city（可选）：城市名称，例如 "Beijing"、"北京" 或 "Beijing,CN"
• lat（可选）：纬度（-90 到 90）
• lon（可选）：经度（-180 到 180）
• zip（可选）：邮政编码，例如 "10001,US"
• units（可选）：单位制（metric/imperial/standard）
• lang（可选）：语言代码（zh_cn/en/es/fr/de/ja/ko/ru）

智能城市名称支持：

• ✅ "北京"（中文）→ 自动可用
• ✅ "Beijing"（英文）→ 自动可用
• ✅ "上海"（中文）→ 自动可用
• ✅ "Shanghai"（英文）→ 自动可用

示例：

{
  "city": "北京",
  "units": "metric",
  "lang": "zh_cn"
}

2. 天气预报（get_weather_forecast）

获取 5 天天气预报数据。

参数：

• 位置参数与上述相同
• cnt（可选）：预报时间点数量（最多 40 个）

示例：

{
  "lat": 39.9042,
  "lon": 116.4074,
  "cnt": 16,
  "units": "metric"
}

3. 空气质量（get_air_quality）

获取空气质量数据。

参数：

• lat：纬度
• lon：经度
• start（可选）：开始时间戳（用于历史数据）
• end（可选）：结束时间戳（用于历史数据）

4. 天气地图（get_weather_map）

获取天气地图瓦片。

参数：

• layer：图层类型（clouds_new/precipitation_new/pressure_new/wind_new/temp_new）
• z：缩放级别（0-10）
• x：瓦片 X 坐标
• y：瓦片 Y 坐标

5. 天气预警（get_weather_alerts）

获取天气预警信息。

参数：

• lat：纬度
• lon：经度

6. 历史天气（get_historical_weather）

查询历史天气数据。

参数：

• lat：纬度
• lon：经度
• dt：查询日期的 Unix 时间戳
• units：单位制
• lang：语言代码

7. 地理编码 (geocoding)

根据地点名称获取坐标。

参数：

• q：位置查询字符串
• limit：返回结果数量（1-5）

8. 反向地理编码 (reverse_geocoding)

根据坐标获取地点名称。

参数：

• lat：纬度
• lon：经度
• limit：返回结果数量（1-5）

📝 使用示例

查询北京当前天气

{
  "tool": "get_current_weather",
  "parameters": {
    "city": "北京",
    "units": "metric",
    "lang": "zh_cn"
  }
}

获取上海 5 天天气预报

{
  "tool": "get_weather_forecast",
  "parameters": {
    "city": "上海",
    "units": "metric",
    "lang": "zh_cn"
  }
}

查询空气质量

{
  "tool": "get_air_quality",
  "parameters": {
    "lat": 39.9042,
    "lon": 116.4074
  }
}

🌍 智能城市名称查询的工作方式

1. 直接查询：首先尝试使用提供的城市名称直接查询天气
2. 自动回退：如果直接查询失败（404 错误），则自动触发地理编码
3. 坐标转换：通过地理编码 API 将城市名称转换为精确坐标
4. 重新查询：使用获取的坐标重新查询天气数据
5. 无缝体验：整个过程对用户透明，无需手动处理

这意味着你可以使用任何语言的城市名称：

• 中文：北京、上海、广州、深圳
• 英文：Beijing, Shanghai, Guangzhou, Shenzhen
• 其他语言：東京、ソウル、Paris, London

🔧 开发

项目结构

src/
├── index.ts              # MCP server entry point
├── types/
│   ├── weather.ts        # Weather data type definitions
│   └── mcp.ts           # MCP tool type definitions
├── services/
│   └── openweather.ts   # OpenWeatherMap API service
└── tools/
    ├── current-weather.ts    # Current weather tool
    ├── forecast.ts          # Weather forecast tool
    ├── air-pollution.ts     # Air quality tool
    ├── weather-maps.ts      # Weather maps tool
    ├── weather-alerts.ts    # Weather alerts tool
    └── historical-weather.ts # Historical weather tool

构建和测试

# Install dependencies
npm install

# Build project
npm run build

# Development mode (watch file changes)
npm run dev

# Run tests
npm test

# Code linting
npm run lint

🌍 支持的位置格式

城市名称

• "北京" - 中文城市名称
• "Beijing" - 英文城市名称
• "Beijing,CN" - 城市名称 + 国家代码
• "New York,US" - 完整格式

坐标

• 纬度：-90 至 90
• 经度：-180 至 180
• 示例：lat: 39.9042, lon: 116.4074

邮政编码

• "10001,US" - 美国邮政编码
• "100000,CN" - 中国邮政编码

📊 数据格式

温度单位

• metric：摄氏度（°C）
• imperial：华氏度（°F）
• standard：开尔文（K）

风速单位

• metric：米/秒（m/s）
• imperial：英里/小时（mph）

语言支持

• zh_cn：简体中文
• en：英语
• es：西班牙语
• fr：法语
• de：德语
• ja：日语
• ko：韩语
• ru：俄语

⚠️ 重要说明

1. API 限制：免费账户有调用次数限制，请合理使用
2. 历史数据：历史天气数据需要付费订阅
3. One Call API：天气预警功能需要订阅 One Call API 3.0
4. 网络连接：确保服务端能够访问 OpenWeatherMap API

🤝 贡献

欢迎提交 Issues 和 Pull Requests！

📄 许可证

MIT 许可证

🔗 相关链接

• OpenWeatherMap API 文档
• Model Context Protocol
• Claude Desktop
• GitHub 仓库