🌦️ Weekly Weather MCP Server

🌦️ 每周天气 MCP 服务

一款天气预报 MCP（Model Context Protocol）服务，使用 OpenWeatherMap One Call API 3.0 提供全球 8 天天气预报和当前天气状况。

本项目基于 Zippland 的早期项目开发，并进行了修改，以支持完整的一周预报和更多时段的数据点。

功能

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

使用方法

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

1. 访问 OpenWeatherMap 并注册账号
2. 订阅 “One Call API 3.0” 套餐（每天免费提供 1,000 次 API 调用）
3. 等待 API 密钥激活（最长可能需要 1 小时）

关于 One Call API 3.0

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

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

API 使用量和限制

• 免费套餐：每天 1,000 次 API 调用
• 默认限制：每天 2,000 次 API 调用（可在账号中调整）
• 计费：超出每天免费 1,000 次的调用将按照 OpenWeatherMap 的定价收费
• 使用量上限：可在账号中设置调用次数上限，以防超出预算（也可以将使用量限制为免费套餐的上限，确保不会产生费用）
• 达到上限后，你会收到 HTTP 429 错误响应

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

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

# Clone the repository
git clone https://github.com/rossshannon/weekly-weather-mcp.git
cd weekly-weather-mcp

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate  # Windows

# Install dependencies
pip3 install -r requirements.txt

这将安装运行服务和开发工具所需的全部依赖项。

3. 运行服务

提供 API 密钥有两种方式：

方法 1：使用环境变量

# Set environment variables
export OPENWEATHER_API_KEY="your_api_key"  # Linux/Mac
set OPENWEATHER_API_KEY=your_api_key  # Windows

# Run the server
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：地点名称字符串，例如“Beijing”“New York”“Tokyo”。工具会将其地理编码为经纬度坐标。
• api_key：OpenWeatherMap API 密钥（可选；如果未提供，则从环境变量中读取）
• timezone_offset：时区偏移量（小时），例如 Beijing 为 8，New York 为 -4。默认值为 0（UTC 时间）。返回数据中的时间将按此时区准确显示。

get_weather

获取某个地点的综合天气数据，包括当前天气（未来 48 小时）和 8 天预报，并提供详细信息。

返回：

• 当前天气信息
• 未来 48 小时的逐小时预报
• 未来 8 天的逐日预报（今天及之后 7 天）
• 每天早上（9 AM）、下午（3 PM）和晚上（8 PM）的数据点
• 天气摘要和降水概率
• 详细天气信息，包括温度、湿度、风速等

适用于以下场景：

• “🏃‍♂️ 这周哪几天适合去跑步？”
• “🪴 这周哪个晚上最适合在花园里干活？”
• “🪁 接下来哪天风最大，适合放风筝？”
• “💧 这周我需要给花园浇水吗，还是会下雨？”

get_current_weather

获取指定地点的当前天气。

返回：

• get_weather 返回数据的精简子集
• 仅包含当前天气信息（温度、体感温度、天气状况、湿度、风况等）；不包含未来时段的预报数据
• 适用于仅需快速查询当前天气状况的场景

地点查询详情

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

• 可使用简单的地点名称：“Paris”“Tokyo”“New York”
• 为提高准确性，可添加国家代码：“Paris,FR”“London,GB”“Portland,US”
• 对于美国城市，可添加州名缩写：“Portland,OR,US”或“Portland,ME,US”
• 该 API 支持 OpenWeatherMap 可进行地理编码的地球上任何地点
• 地点名称会在内部转换为经纬度坐标

如果找不到地点，API 将返回错误。如果地点存在歧义，请尝试添加国家或州代码，以获得更准确的结果。

使用示例

示例 1：当前天气

User: What’s the weather like in New York right now?

AI: Let me check the current weather in New York for you.
[Calling get_current_weather("New York", timezone_offset=-4)]

Current weather in New York: 5°C, few clouds, humidity 42%, wind speed 4.1m/s.

示例 2：每周计划

User: I need to mow my lawn this week in Boston. Which day would be best?

AI: Let me check the weather forecast for Boston to find the best day for lawn mowing.
[Calling get_weather("Boston", timezone_offset=-4)]

Looking at the Boston forecast for the week:
- Today (Monday): Light rain (28% chance), 5°C
- Tuesday: Clear, sunny, 10°C
- Wednesday: Light rain (100% chance), 9°C
- Thursday: Moderate rain (100% chance), 10°C
- Friday: Moderate rain (100% chance), 11°C
- Saturday: Partly cloudy, 13°C
- Sunday: Scattered clouds, 17°C

Tuesday would be your best option for mowing the lawn. It will be clear and sunny with no chance of rain, and the temperature will be comfortable at around 10°C.

你可以将此 MCP 服务与其他服务结合使用，以实现多步骤工作流。例如，查询天气后，还可以让 Claude 将其添加为日历事件，以提醒自己相关计划。

故障排除

API 密钥问题

如果遇到“Invalid API key”或授权错误：

1. 请确保已订阅“One Call API 3.0”套餐。你需要使用借记卡或信用卡启用账户，但只有超出免费额度时才会收费。
2. 请记住，API 密钥激活最长可能需要一小时
3. 请确认已在环境变量中正确设置 OPENWEATHER_API_KEY，或者检查调用工具时提供的 api_key 参数是否正确

其他常见问题

• “Location not found” 错误：

  • 检查地点名称是否有拼写错误
  • OpenWeatherMap 数据库中可能没有某些非常小或偏远的地点

• 返回的地点不正确：

  • 尝试使用更准确的城市名称，或添加国家代码，例如 “Beijing,CN” 或 “Porto,PT”
  • 对于名称常见的美国城市，请注明州名：“Springfield,IL,US” 或 “Portland,OR,US”
  • 对于不同国家中名称相同的城市，请务必添加国家代码，并在适用时注明州名：“Paris,FR” 表示法国巴黎，“Paris,TX,US” 表示美国得克萨斯州巴黎。

• 速率限制（429 错误）：您已超出 API 调用限制。请检查您的 OpenWeatherMap 账户设置。

开发与测试

测试

本项目包含单元测试、集成测试和模拟客户端测试文件，用于验证 MCP 服务的功能。我们已手动测试该服务，确保它能与 Claude Desktop、Cursor 和其他 MCP 客户端正常配合使用。

手动测试客户端

在 Claude Desktop 或其他 MCP 客户端中配置服务之前，您可以使用随附的测试脚本验证 API 密钥和安装是否正常：

1. 设置您的 OpenWeatherMap API 密钥：

   export OPENWEATHER_API_KEY="your_api_key"
   

2. 运行测试客户端：

   python3 test_mcp_client.py
   

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

1. 您的 API 密钥正常工作
2. 可以访问 OpenWeatherMap API
3. 天气数据函数正常运行

如果测试显示了当前天气数据，您就可以在 Claude Desktop、Cursor 或其他 MCP 客户端中配置服务了！

自动化测试

仓库包含单元测试和集成测试文件，用于：

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

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

运行自动化测试：

# Run unit tests
python test_weather_mcp.py

# Run integration tests
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 小时的逐小时预报
• 纳入天气摘要、风速和降水概率
• 添加单元测试、集成测试和模拟客户端测试文件