使用说明
天气MCP服务器
一个免费、可投入生产的模型上下文协议（MCP）服务器，用于通过OpenWeatherMap API访问天气数据。
🌤️ 概述
这台MCP服务器通过标准化接口提供全面的天气信息，使人工智能助手能够获取实时天气数据、预报、空气质量信息等。
✨ 特点
🛠️ 工具（7个可用）
- 获取当前天气 - 获取任何地点的当前天气
- 获取天气预报 - 获取每3小时一次的5天天气预报
- 搜索位置 - 搜索地点并获取坐标
- 通过坐标获取天气 - 通过纬度/经度获取天气信息
- 获取空气质量信息 - 获取空气质量指数和污染物数据
- 比较天气 - 比较多个城市的天气
- 获取天气警报 - 获取恶劣天气警报（注：需付费订阅）
📚 资源（4个可用）
weather://current- 当前天气数据weather://forecast- 天气预报weather://alerts- 天气警报和预警weather://history- 历史天气数据
🚀 快速入门
先决条件
-
免费API密钥 来自OpenWeatherMap：
- 在 https://openweathermap.org/api 进行注册
- 前往API密钥部分
- 复制您的API密钥（免费套餐包含每天1000次调用）
-
Python 3.10及以上版本
安装
cd weather-mcp-server
pip install -e .
配置
# Set your API key
export OPENWEATHER_API_KEY="your_api_key_here"
# Or create a .env file
echo "OPENWEATHER_API_KEY=your_api_key_here" > .env
运行服务器
python server.py
💡 使用示例
使用 Claude Desktop
添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：
{
"mcpServers": {
"weather": {
"command": "python",
"args": ["/full/path/to/weather-mcp-server/server.py"],
"env": {
"OPENWEATHER_API_KEY": "your_api_key_here"
}
}
}
}
然后问克劳德：
- “巴黎的天气怎么样？”
- “比较纽约、伦敦和东京的天气”
- “给我提供西雅图未来5天的天气预报”
- “北京的空气质量怎么样？”
使用 Cursor IDE
创造 .cursor/config.json：
{
"mcp": {
"servers": {
"weather": {
"command": "python",
"args": ["server.py"],
"cwd": "/full/path/to/weather-mcp-server",
"env": {
"OPENWEATHER_API_KEY": "your_api_key_here"
}
}
}
}
}
程序化使用
from mcp.client import Client
import asyncio
async def main():
async with Client() as client:
await client.connect_stdio(
command="python",
args=["server.py"],
env={"OPENWEATHER_API_KEY": "your_key"}
)
# Get current weather
result = await client.call_tool(
"get_current_weather",
{"location": "London,UK", "units": "metric"}
)
print(result)
# Get forecast
forecast = await client.call_tool(
"get_forecast",
{"location": "New York,NY,US", "units": "imperial", "days": 3}
)
print(forecast)
asyncio.run(main())
🔧 工具详情
获取当前天气
获取某地的当前天气状况。
参数：
location（必填）：城市名称，例如，“London,UK”（英国伦敦），“New York,NY,US”（美国纽约）units（可选）：“metric”（摄氏度）、“imperial”（华氏度）或“standard”（开尔文）
返回值：
{
"location": {
"name": "London",
"country": "GB",
"coordinates": {"latitude": 51.51, "longitude": -0.13}
},
"current": {
"temperature": 15.5,
"feels_like": 14.2,
"humidity": 72,
"description": "partly cloudy",
"wind": {"speed": 5.2, "direction": 230},
"pressure": 1013,
"visibility": 10000
},
"sunrise": "2024-10-16T06:42:00",
"sunset": "2024-10-16T18:15:00"
}
获取天气预报
获取每3小时更新一次的5天天气预报。
参数：
location（必填）：城市名称units（可选）：温度单位days（可选）：天数（1-5，默认5）
返回值：
{
"location": {"name": "Paris", "country": "FR"},
"forecast": [
{
"datetime": "2024-10-16T12:00:00",
"temperature": 18.5,
"description": "light rain",
"humidity": 65,
"pop": 0.3
}
]
}
搜索位置
搜索一个地点并获取其坐标。
参数：
query（必填）：要搜索的位置名称limit（可选）：最大结果数（默认5）
返回值：
{
"query": "Springfield",
"results": [
{
"name": "Springfield",
"country": "US",
"state": "Illinois",
"coordinates": {"latitude": 39.78, "longitude": -89.65}
}
]
}
通过坐标获取天气
获取特定坐标的天气信息。
参数：
latitude（必填）：纬度longitude（必填）：经度units（可选）：温度单位
获取空气质量信息
获取空气质量指数和污染物浓度。
参数：
latitude（必填）：纬度longitude（必填）：经度
返回：
{
"air_quality_index": 2,
"aqi_level": "Fair",
"components": {
"co": 201.94,
"no2": 13.56,
"o3": 68.66,
"pm2_5": 5.28,
"pm10": 7.32
}
}
比较天气
比较多个城市的当前天气。
参数：
locations（必填）：城市名称数组（2-5个城市）units（可选）：温度单位
返回值： 所有地点的天气数据对比。
📊 API限制
免费套餐（OpenWeatherMap）
- 每日通话次数： 一千
- 每分钟通话次数： 六十
- 包含的功能有：
- 当前天气
- 5天天气预报
- 地理编码
- 空气污染数据
缓存
服务器会自动缓存响应10分钟，以减少API调用。
🌍 支持的单位
- 指标温度以摄氏度计，风速以米/秒计
- **“imperial”翻译成中文是“帝国的”或“英制的”（根据上下文，可能指与英制单位相关的）**温度以华氏度为单位，风速以英里每小时为单位
- 标准开尔文温度，风速以米每秒计
🔐 安全
- API密钥存储在环境变量中（绝不在代码中）
- 与OpenWeatherMap进行仅HTTPS的通信
- 对所有参数进行输入验证
- 速率限制意识
🐞 故障排除
“API密钥未配置”错误
# Make sure you set the environment variable
export OPENWEATHER_API_KEY="your_key"
# Or check if it's set
echo $OPENWEATHER_API_KEY
“401 未授权”错误
- 请验证您的API密钥是否正确
- 检查API密钥是否已激活（注册后可能需要几个小时）
- 确保你正确地使用了免费套餐
速率限制错误
免费套餐允许每分钟60次调用，每天1000次。服务器会缓存响应10分钟，以帮助避免达到调用限制。
📚 资源
- OpenWeatherMap API 文档： https://openweathermap.org/api 翻译为中文是：“https://openweathermap.org/（开放天气）API” 或者简化为 “开放天气API官网”
- 免费API注册： https://openweathermap.org/price（中文可表述为：“OpenWeatherMap 价格页面”或“OpenWeatherMap 定价信息”）
- MCP规范： https://modelcontextprotocol.io（该网址可直接翻译为“模型上下文协议.io”，但实际使用中网址通常保持原样，不进行翻译）
- OpenWeatherMap 天气代码： https://openweathermap.org/天气状况（或：天气条件）
🧪 测试
# Run tests
pytest tests/ -v
# Test specific tool
python -c "
import asyncio
from server import WeatherMCPServer
async def test():
server = WeatherMCPServer()
result = await server._get_current_weather({
'location': 'London,UK',
'units': 'metric'
})
print(result)
asyncio.run(test())
"
🎯 示例查询
询问你的AI助手：
-
当前天气：
- “东京的天气怎么样？”
- “现在西雅图下雨了吗？”
- “迈阿密的温度是多少？”
-
预测：
- “给我一份巴黎未来3天的天气预报”
- “这周伦敦会下雨吗？”
- “纽约明天的天气怎么样？”
-
比较：
- “比较悉尼、伦敦和纽约的天气”
- “迪拜和曼谷，哪个更暖和？”
-
空气质量：
- “德里的空气质量怎么样？”
- “洛杉矶的空气质量好吗？”
-
位置搜索：
- “查找所有名为波特兰的城市”
- “搜索斯普林菲尔德的地点”
💻 开发
项目结构
weather-mcp-server/
├── server.py # Main server implementation
├── README.md # This file
├── requirements.txt # Python dependencies
├── pyproject.toml # Package configuration
└── tests/ # Test suite
└── test_server.py
添加自定义工具
# In server.py, add to list_tools():
Tool(
name="your_custom_tool",
description="Description",
inputSchema={...}
)
# Add handler method:
async def _your_custom_tool(self, args):
# Implementation
pass
# Add to call_tool():
elif name == "your_custom_tool":
result = await self._your_custom_tool(arguments)
📄 许可证
MIT 许可证 - 免费使用、修改和分发
🤝 贡献
欢迎投稿！请：
- 为仓库创建分支（或：克隆仓库）
- 创建一个特性分支
- 添加测试
- 提交拉取请求
⭐ 即将推出的功能
- 历史天气数据
- 天气图
- 紫外线指数信息
- 海洋天气数据
- 农业气象数据
📞 支持
- 问题： GitHub 问题（或“GitHub 问题追踪”）
- OpenWeatherMap 支持： https://openweathermap.org/faq（中文可表述为：“https://openweathermap.org/常见问题解答”）
- MCP社区： https://modelcontextprotocol.io（该网址可直接翻译为中文表述，但通常网址保持原样不翻译，若需说明其含义，可表述为“Model Context Protocol 的官方网站”）
使用OpenWeatherMap免费API，用心打造
只需5分钟，即可开始使用免费天气数据为您的AI赋能！
