MCP server for weather and climate data queries with intelligent file saving
npm install xmo-weather-mcp

MCP (Model Context Protocol) server for weather and climate data queries with intelligent file saving.
基于经纬度的天气与气候数据查询 MCP 服务器,支持智能文件保存到用户工作目录。
无需安装,直接使用:
``bash`
npx -y @xmo/weather-mcp
在 Claude Desktop 配置文件中添加 (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
`json`
{
"mcpServers": {
"weather-mcp": {
"command": "npx",
"args": ["-y", "@xmo/weather-mcp"],
"env": {
"XMO_APIKEY": "your-api-key-here"
}
}
}
}
`bash`
npm install -g @xmo/weather-mcp
配置文件:
`json`
{
"mcpServers": {
"weather-mcp": {
"command": "weather-mcp",
"env": {
"XMO_APIKEY": "your-api-key-here"
}
}
}
}
点击查看 Python 版本安装方式
`bash`
cd /Users/yuzuoyang/PycharmProjects/weather-mcp
pip install -e .
配置文件:
`json`
{
"mcpServers": {
"weather-mcp": {
"command": "python",
"args": ["/Users/yuzuoyang/PycharmProjects/weather-mcp/server.py"],
"env": {
"XMO_APIKEY": "your-api-key"
}
}
}
}
注意: Node.js 版本更加方便且易于使用,推荐使用 npx 方式。
核心特点:
- ✅ 自动计算并展示费用
- ✅ 直接查询,无需预估
- ✅ 智能场景识别
参数:
`json`
{
"latitude": 30.0,
"longitude": 120.0,
"start_datetime": "2025-01-01 00:00:00",
"end_datetime": "2025-01-02 00:00:00",
"use_case": "solar",
"freq": 15,
"output_file": "weather_data.csv" // 可选
}
use_case 场景:
- basic: 基础天气 - 温度、湿度、降水、风速(默认)solar
- / 光伏: 光伏场景 - 辐射、温度、云量、日照wind
- / 风电: 风电场景 - 多高度风速、风向air_quality
- / 空气质量: PM2.5, PM10, AQI, 臭氧等all
- / 所有: 所有可用元素
freq 时间间隔: 5, 15, 30, 60 分钟(默认 60)
返回:
- CSV 文件路径(保存在用户当前工作目录)
- 查询参数摘要
- 自动展示费用
文件保存规则:
1. 未指定 output_file: 保存到当前工作目录,自动命名
2. 指定相对路径: 相对于当前工作目录
3. 指定绝对路径: 使用指定的绝对路径
核心特点:
- ✅ 自动计算并展示费用
- ✅ 直接查询,无需预估
- ✅ 适用于长期规划
参数:
`json`
{
"latitude": 30.0,
"longitude": 120.0,
"start_date": "2026-01-01",
"end_date": "2026-12-31",
"use_case": "solar",
"output_file": "climate_data.csv" // 可选
}
use_case 场景:
- basic: 基础气候 - 温度、降水、湿度、风速(默认)solar
- / 光伏: 光伏场景 - 辐射、温度、云量、蒸发量wind
- / 风电: 风电场景 - 风速、温度、气压agriculture
- / 农业: 农业场景 - 温度、降水、湿度、土壤湿度all
- / 所有: 所有可用变量
返回:
- CSV 文件路径(保存在用户当前工作目录)
- 查询参数摘要
- 自动展示费用
文件保存规则: 同天气数据
`
User: 查询(120, 30)未来3天15分钟颗粒度的光伏相关天气数据
AI: (调用 query_weather_data)
✅ 天气数据查询成功
查询参数:
- 位置: (120, 30)
- 时间: 2026-01-20 00:00:00 ~ 2026-01-23 00:00:00
- 间隔: 15 分钟
- 场景: 光伏场景 (8 个元素)
💰 预估费用: 0.4 调用量
输出文件: weather_lat30.0_lon120.0_20260120_20260123.csv
`
`
User: 获取(113.3, 23.1)未来一年的风电相关气候数据
AI: (调用 query_climate_data,use_case="wind")
✅ 气候数据查询成功
查询参数:
- 位置: (113.3, 23.1)
- 日期: 2026-01-20 ~ 2027-01-20
- 场景: 风电场景 (4 个变量)
💰 预估费用: 1.0 调用量
输出文件: climate_lat23.1_lon113.3_20260120_20270120.csv
`
`
User: 查询北京(116.4, 39.9)昨天的小时级空气质量数据
AI: (调用 query_weather_data,use_case="air_quality")
✅ 天气数据查询成功
💰 预估费用: 0.2 调用量
输出文件: 包含 PM2.5, PM10, AQI 等数据
`
`
User: 给我(120, 30)从2025年1月1日到1月3日,30分钟间隔的温度和辐照度数据
AI: 理解需求,转换为:
- use_case: solar (因为提到了辐照度)
- freq: 30
调用 query_weather_data 获取数据
`
| 特性 | 天气数据 | 气候数据 |
|------|---------|---------|
| 时间粒度 | 5/15/30/60 分钟 | 按日 (daily) |
| 时间范围 | 1940 ~ D+14 | 历史 ~ 未来50年 |
| 主要用途 | 短期预报、实时监测 | 长期规划、趋势分析 |
| 数据类型 | 实时天气、空气质量 | 日聚合统计 |
| 典型场景 | 空气质量分析、短期光伏预测 | 年发电量预测、气候研究 |
#### 天气数据费用
`python等效天数
data_points = (end - start).total_minutes / freq
points_per_day = 24 * 60 / freq
equivalent_days = data_points / points_per_day
示例: 1天 × 60分钟间隔 × 6元素 × 1位置 ≈ 0.2 调用量
#### 气候数据费用
`python
time_weight = n_days / 14.0
variables_weight = n_variables / 10.0
variable_time_weight = max(variables_weight, time_weight * variables_weight)
total_cost = ceil(max(1.0, variable_time_weight) n_locations) 0.1
`示例: 90天 × 9变量 × 1位置 ≈ 0.6 调用量
文件保存机制 / File Saving
$3
所有查询结果 CSV 文件自动保存到用户当前工作目录。
`bash
如果你在这个目录运行 Claude Desktop
/Users/yourname/projects/my-project/那么文件会保存到
/Users/yourname/projects/my-project/weather_lat30.0_lon120.0_20260120_20260123.csv
`$3
#### 自动命名(未指定 output_file)
天气数据:
`
weather_lat{纬度}_lon{经度}_{开始日期}_{结束日期}.csv
示例: weather_lat30.0_lon120.0_20260120_20260123.csv
`气候数据:
`
climate_lat{纬度}_lon{经度}_{开始日期}_{结束日期}.csv
示例: climate_lat30.0_lon120.0_20260101_20261231.csv
`#### 自定义命名(指定 output_file)
相对路径 - 相对于当前工作目录:
`json
{
"output_file": "data/solar_data.csv"
}
// 保存到: /Users/yourname/projects/my-project/data/solar_data.csv
`绝对路径 - 直接使用指定路径:
`json
{
"output_file": "/Users/yourname/Downloads/weather.csv"
}
// 保存到: /Users/yourname/Downloads/weather.csv
`仅文件名 - 保存到当前工作目录:
`json
{
"output_file": "my_weather.csv"
}
// 保存到: /Users/yourname/projects/my-project/my_weather.csv
`$3
#### 场景 1: 自动命名(推荐)
`
User: 查询(120, 30)未来3天的光伏数据结果:
📁 /Users/yourname/current-dir/weather_lat30.0_lon120.0_20260120_20260123.csv
`#### 场景 2: 指定文件名
`
User: 查询(120, 30)未来3天的光伏数据,保存为 solar_forecast.csvAI 会设置: output_file = "solar_forecast.csv"
结果:
📁 /Users/yourname/current-dir/solar_forecast.csv
`#### 场景 3: 指定子目录
`
User: 查询(120, 30)未来3天的光伏数据,保存到 data/weather/ 目录AI 会设置: output_file = "data/weather/solar_data.csv"
结果:
📁 /Users/yourname/current-dir/data/weather/solar_data.csv
(目录不存在会自动创建)
`技术架构 / Architecture
`
weather-mcp/
├── server.py # MCP 服务器主文件
├── generate-weather/ # 天气数据模块
│ ├── fetch_weather_history.py # 天气数据获取
│ ├── elements.csv # 天气元素配置
│ └── SKILL.md # 天气数据说明
├── generate-climate/ # 气候数据模块
│ ├── fetch_climate.py # 气候数据获取
│ ├── variables.csv # 气候变量配置
│ └── SKILL.md # 气候数据说明
├── pyproject.toml # 项目配置
└── README.md # 本文件
`环境要求 / Requirements
$3
- Node.js >= 18.0.0
- @modelcontextprotocol/sdk >= 0.5.0
- axios >= 1.6.0$3
- Python >= 3.10
- MCP >= 0.1.0
- requests >= 2.31.0
- pandas >= 2.0.0Node.js vs Python 对比
| 特性 | Node.js (本包) | Python 版本 |
|------|----------------|-------------|
| 安装方式 |
npx -y @xmo/weather-mcp | pip install + 路径配置 |
| 配置复杂度 | 一行配置即可 | 需要指定完整路径 |
| 更新方式 | npx 自动使用最新版本 | 手动升级 |
| 分发方式 | npm 仓库 | 手动下载 |
| 依赖管理 | 自动管理 | 手动管理 |
| 跨平台 | ✅ 完全支持 | ✅ 完全支持 |
| 用户体验 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| 推荐使用 | ✅ 强烈推荐 | ❌ 已弃用 |故障排查 / Troubleshooting
$3
`
❌ 错误: XMO_APIKEY 环境变量未设置
`
解决方案: 设置环境变量 export XMO_APIKEY=your-api-key$3
`
❌ 错误: 时间间隔必须是 [5, 15, 30, 60] 之一
`
解决方案: 使用支持的频率值: 5, 15, 30, 或 60 分钟$3
`
❌ 错误: 纬度必须在 -90 到 90 之间
``- MCP Documentation
- 天气数据 API 文档
- 气候数据 API 文档
MIT License