🌦️ 每周天气MCP服务器
天气预报MCP（模型上下文协议）服务器提供 8天全球天气预报 使用 OpenWeatherMap 一次调用API 3.0.
该项目是在早期项目的基础上构建的 Zippland，并进行了修改，以支持整周预测和额外的时间数据点。
Animation showing Claude Desktop processing the weather data from the MCP Server
Claude Desktop showing a detailed weather forecast with lawn mowing recommendations
特性
- 🌍 支持查询世界各地的天气状况
- 🌤️ 未来48小时的每小时预测
- 📅 提供详细的8天预报（今天+接下来的7天），包括上午、下午和晚上的数据点
- 🌧️ 天气概要和降水概率
- 🌡️ 详细的天气信息，包括温度、湿度、风速等。
- 📍 支持在不同时区报告结果
- 🗂️ 不需要单独的配置文件；API密钥可以直接通过环境变量或参数传递
用法
1.使用One Call API 3.0 Access获得OpenWeatherMap API密钥（免费）
- 访问 OpenWeatherMap 并注册一个帐户
- 订阅“一次呼叫API 3.0”计划（每天免费提供1000个API呼叫）
- 等待API密钥激活（这可能需要一个小时）
关于One Call API 3.0
One Call API 3.0提供全面的天气数据：
- 当前天气状况
- 1小时的分钟预报
- 48小时的每小时预报
- 8天（包括今天）的每日预报
- 国家天气警报
- 历史天气数据
API使用和限制
- 免费套餐：每天1000个API调用
- 默认限制：每天2000个API调用（可在您的帐户中进行调整）
- 计费：任何超过免费1000/天的通话将根据OpenWeatherMap定价收取费用
- 使用上限：您可以在帐户中设置通话限制，以防止超出预算（包括将您的使用限制在免费等级限制内，这样就不会产生任何费用）
- 如果达到限制，您将收到HTTP 429错误响应
备注：API密钥激活可能需要几分钟到一小时。如果在订阅或生成新密钥后不久收到身份验证错误，请稍等片刻，稍后重试。
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支持的客户端（例如。， 克劳德桌面 (说明), 光标):
{
"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天气
获取指定位置的当前天气。
退货：
- 返回的数据的简化子集
get_weather - 只有当前的天气信息（温度、感觉、天气状况、湿度、风等）；没有未来时间段的预测数据
- 仅适用于快速查询当前状况
位置查找详细信息
这 location 参数使用OpenWeatherMap的地理编码将位置名称转换为地理坐标：
- 简单的地名有效：“巴黎”、“东京”、“纽约”
- 为了提高准确性，请包括国家代码：“法国巴黎”、“英国伦敦”、“美国波特兰”
- 对于美国城市，您可以包括州：“美国俄勒冈州波特兰”或“美国缅因州波特兰”
- 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服务器与其他服务器结合使用，以实现多步骤工作流。例如，一旦检查了天气，你也可以告诉克劳德将其添加为日历中的事件，以提醒自己这些计划。
Calendar event created by Claude based on the weather forecast
故障排除
API关键问题
如果您遇到“无效的API密钥”或授权错误：
- 请确保您已订阅“一次呼叫API 3.0”计划。您需要借记卡或信用卡才能启用您的帐户，但只有当您超过免费等级限制时，才会向您收费。
- 请记住，API密钥激活可能需要一个小时
- 验证您是否已设置
OPENWEATHER_API_KEY在环境变量中正确输入，或检查您是否提供了正确的api_key调用工具时的参数
其他常见问题
- “找不到位置”错误:
- 检查位置名称中的拼写错误 - 一些非常小或偏远的位置可能不在OpenWeatherMap的数据库中
- 返回的位置不正确:
- 尝试使用更准确的城市名称或添加国家代码，例如“中国北京”或“葡萄牙波尔图” - 对于有共同名称的美国城市，请指定州：“美国伊利诺伊州斯普林菲尔德”或“美国俄勒冈州波特兰” - 对于不同国家的同名城市，请务必包括国家代码和州（如适用）：“Paris，FR”代表法国巴黎，“Paris，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客户端配置服务器了！
Running local test client to verify API key and installation
自动化测试
存储库包括单元和集成测试文件，这些文件：
- 测试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服务器在任何修改后仍能正常运行。
鸣谢
这个项目改编自原著 天气MCP Zippland。修改内容包括：
- 与OpenWeatherMap One Call API 3.0集成
- 将预测数据从2天延长到8天（今天+7天）
- 增加每天上午、下午和晚上的数据点
- 未来48小时的每小时预测
- 包括天气摘要、风速和降水概率
- 单元测试、集成测试和模拟客户端测试文件