周天气-mcp

Name: 周天气-mcp
Author: rossshannon

作者：rossshannon7 星标更新：2025-04-11

安装使用来源：spider==github.com

项目介绍

🌦️ 每周天气 MCP 服务器

这是一个使用 OpenWeatherMap 的 One Call API 3.0 提供全球8天天气预报及当前天气状况的天气预报 MCP（模型上下文协议）服务器。

该项目基于 Zippland 的早期项目进行了修改，以支持整周的天气预报以及额外的时间段数据点。

<div align="center"> <img src="https://rossshannon.github.io/weekly-weather-mcp/images/weather-mcp-thinking.gif" alt="Claude 调用 MCP 服务器" width="800"> <p><em>Claude Desktop 处理来自 MCP 服务器的天气数据的动画</em></p> </div> <br> <div align="center"> <img src="https://rossshannon.github.io/weekly-weather-mcp/images/weather-forecast-example.png" alt="Claude 显示天气预报" width="700"> <p><em>Claude Desktop 显示详细的天气预报，包括草坪修剪建议</em></p> </div>

功能

🌍 支持查询全球任意地点的天气状况
🌤️ 下一小时内的每小时天气预报
📅 提供详细的8天天气预报（今天+接下来的7天），包括早晨、下午和晚上的数据点
🌧️ 天气总结和降水概率
🌡️ 详细的天气信息，包括温度、湿度、风速等
📍 支持在不同时区报告结果
🗂️ 不需要单独的配置文件；可以通过环境变量或参数直接传递 API 密钥

使用方法

1. 获取具有 One Call API 3.0 访问权限的 OpenWeatherMap API 密钥（免费）

访问 OpenWeatherMap 并注册一个账户
订阅“One Call API 3.0”计划（提供每天1000次免费调用）
等待 API 密钥激活（这可能需要一个小时）

关于 One Call API 3.0

One Call API 3.0 提供全面的天气数据：

当前天气状况
未来1小时的分钟级预报
下48小时的每小时预报
未来8天的每日预报（包括今天）
国家天气警报
历史天气数据

API 使用和限制

免费层级：每天1000次调用
默认限制：每天2000次调用（可以在您的账户中调整）
计费：超出免费的1000次/天后，根据 OpenWeatherMap 定价进行收费
使用上限：您可以在账户中设置调用限制，以防止超出预算（包括将使用限制设置在免费层级内，以避免产生费用）
如果达到限制，您将收到 HTTP 429 错误响应

注意：API 密钥激活可能需要几分钟到一个小时。如果您在订阅或生成新密钥后不久收到身份验证错误，请稍等片刻再试一次。

2. 克隆仓库并安装依赖项

# 克隆仓库
git clone https://github.com/rossshannon/weekly-weather-mcp.git
cd weekly-weather-mcp

# 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或者
venv\Scripts\activate  # Windows

# 安装依赖项
pip3 install -r requirements.txt

这将安装运行服务器和开发工具所需的所有必要依赖项。

3. 运行服务器

有两种方式提供 API 密钥：

方法1：使用环境变量

# 设置环境变量
export OPENWEATHER_API_KEY="your_api_key"  # Linux/Mac
set OPENWEATHER_API_KEY=your_api_key  # Windows

# 运行服务器
python weather_mcp_server.py

方法2：调用工具时提供

无需设置环境变量直接运行：

python weather_mcp_server.py

调用工具时，您需要提供 api_key 参数。

4. 在 MCP 客户端配置中使用

将以下配置添加到您的 MCP 支持客户端（例如，Claude Desktop (指南)，Cursor）：

{
  "weather_forecast": {
    "command": "python3",
    "args": [
      "/full_path/weather_mcp_server.py"
    ],
    "env": {
      "OPENWEATHER_API_KEY": "your_openweathermap_key_here"
    },
    "disabled": false,
    "autoApprove": ["get_weather", "get_current_weather"]
  }
}

如果使用虚拟环境，您的配置应包括虚拟环境中 Python 可执行文件的完整路径：

{
  "weather_forecast": {
    "command": "/full_path/venv/bin/python3",
    "args": [
      "/full_path/weather_mcp_server.py"
    ],
    "env": {
      "OPENWEATHER_API_KEY": "your_openweathermap_key_here"
    },
    "disabled": false,
    "autoApprove": ["get_weather", "get_current_weather"]
  }
}

5. 可用工具

服务器暴露了两个工具，get_weather 和 get_current_weather。这两个工具接受相同的参数：

location：作为字符串的位置名称，例如“北京”，“纽约”，“东京”。该工具会处理地理编码，将其转换为经纬度坐标。
api_key：OpenWeatherMap API 密钥（可选，如果没有提供，则从环境变量读取）
timezone_offset：时区偏移量（小时），例如北京为8，纽约为-4。默认是0（UTC时间）。返回的数据中的时间将准确对应这个时区。

get_weather

获取指定位置的综合天气数据，包括当前天气（未来48小时）和8天预报，带有详细信息。

当前天气信息
下48小时的每小时预报
未来8天的每日预报（今天+接下来的7天）
每天的早晨（上午9点）、下午（下午3点）和晚上（晚上8点）的数据点
天气总结和降水概率
详细的天气信息，包括温度、湿度、风速等

适用于以下场景：

“🏃‍♂️ 这周哪几天适合跑步？”
“🪴 这周哪个傍晚最适合在花园工作？”
“🪁 接下来哪一天最适合放风筝？”
“💧 这周我是否需要给花园浇水，还是雨水会照顾好它？”

get_current_weather

获取指定位置的当前天气。

get_weather 返回数据的一个简化子集
仅当前天气信息（温度、体感温度、天气状况、湿度、风速等）；不包括未来时间段的预报数据
仅用于快速查询当前条件

地址查找细节

location 参数使用 OpenWeatherMap 的地理编码将地址名称转换为地理坐标：

简单的地址名称有效：“巴黎”，“东京”，“纽约”
为了更精确，可以包含国家代码：“巴黎,FR”，“伦敦,GB”，“波特兰,US”
对于美国城市，可以包含州：“波特兰,OR,US” 或 “波特兰,ME,US”
API 支持 OpenWeatherMap 可以地理编码的地球上任何位置
地址名称内部被转换为经纬度坐标

如果无法找到地址，API 将返回错误。对于模糊的地址，尝试添加国家或州代码以获得更精确的结果。

使用示例

示例1：当前天气

用户：纽约现在的天气怎么样？

AI：让我为您检查纽约的当前天气。
[调用 get_current_weather("纽约", timezone_offset=-4)]

纽约当前天气：5°C，少量云，湿度42%，风速4.1m/s。

示例2：每周规划

用户：我需要在波士顿割草。这周哪一天最好？

AI：让我查看波士顿的天气预报，找出最适合割草的日子。
[调用 get_weather("波士顿", timezone_offset=-4)]

查看波士顿本周的天气预报：
- 今天（周一）：小雨（28%几率），5°C
- 周二：晴朗，10°C
- 周三：小雨（100%几率），9°C
- 周四：中雨（100%几率），10°C
- 周五：中雨（100%几率），11°C
- 周六：多云，13°C
- 周日：部分多云，17°C

周二将是您割草的最佳选择。那天晴朗无雨，气温约为10°C，非常舒适。

您可以结合其他 MCP 服务器实现多步骤工作流。例如，在检查完天气后，还可以让 Claude 将此事件添加到您的日历中，提醒您这些计划。

<div align="center"> <img src="https://rossshannon.github.io/weekly-weather-mcp/images/calendar-integration-example.png" alt="由 Claude 创建的日历事件" width="365"> <p><em>基于天气预报由 Claude 创建的日历事件</em></p> </div>

故障排除

API 密钥问题

如果您遇到“无效 API 密钥”或授权错误：

确保您已订阅“One Call API 3.0”计划。您需要一张借记卡或信用卡来启用账户，但只有超出免费层级限制时才会被收费。
记住 API 密钥激活可能需要一个小时
验证您是否正确设置了环境变量中的 OPENWEATHER_API_KEY，或者检查您在调用工具时提供的 api_key 参数是否正确

其他常见问题

“未找到位置”错误：
- 检查地址名称是否有拼写错误
- 一些非常小或偏远的地方可能不在 OpenWeatherMap 的数据库中
返回的地址不正确：
- 尝试使用更准确的城市名称或添加国家代码，例如“北京,CN”或“波尔图,PT”
- 对于美国城市，如果有相同名称，指定州：“斯普林菲尔德,IL,US”或“波特兰,OR,US”
- 对于同名但在不同国家的城市，始终包含国家代码和州（如适用）：“巴黎,FR”代表法国巴黎，“巴黎,TX,US”代表美国得克萨斯州的巴黎。
速率限制（429 错误）：您已超过 API 调用限制。检查您的 OpenWeatherMap 账户设置。

开发和测试

测试

本项目包括单元测试、集成测试和模拟客户端测试文件，以验证 MCP 服务器的功能。服务器已经手动测试，确保其与 Claude Desktop、Cursor 和其他 MCP 客户端正常工作。

手动客户端测试

在使用 Claude Desktop 或其他 MCP 客户端配置服务器之前，您可以使用包含的测试脚本来验证您的 API 密钥和安装：

设置您的 OpenWeatherMap API 密钥：

export OPENWEATHER_API_KEY="your_api_key"

运行测试客户端：
```
python3 test_mcp_client.py
```

测试脚本直接调用天气函数，检查纽约的当前天气，并显示结果。这有助于验证：

您的 API 密钥是否正常工作
OpenWeatherMap API 是否可访问
天气数据函数是否正常运行

如果测试显示当前天气数据，您就可以配置服务器与 Claude Desktop、Cursor 或其他 MCP 客户端一起使用！

<div align="center"> <img src="https://rossshannon.github.io/weekly-weather-mcp/images/weather-mcp-test-client.png" alt="运行本地测试客户端" width="800"> <p><em>运行本地测试客户端以验证 API 密钥和安装</em></p> </div>

自动化测试

仓库包括单元测试和集成测试文件，它们：

测试 API 密钥的处理和验证
验证数据解析和格式化
验证 API 失败的错误处理
测试暴露的两个 MCP 工具：get_weather 和 get_current_weather

这些测试需要正确设置开发环境并安装所有依赖项。它们作为未来开发的参考。

要运行自动化测试：

# 运行单元测试
python test_weather_mcp.py

# 运行集成测试
python test_mcp_integration.py

测试使用示例 API 响应（test_weather_response.json）来模拟来自 OpenWeatherMap API 的响应，因此可以在没有 API 密钥或互联网连接的情况下运行。

这些测试作为未来开发的参考，确保 MCP 服务器在任何修改后仍能正常工作。

致谢

该项目改编自 Zippland 的原始 Weather MCP。修改包括：

集成 OpenWeatherMap One Call API 3.0
将预报数据从2天扩展到8天（今天+接下来的7天）
添加每天的早晨、下午和晚上的数据点
下48小时的每小时预报
包括天气总结、风速和降水概率
单元测试、集成测试和模拟客户端测试文件