Weather MCP Server


MCP (Model Context Protocol) server for weather and climate data queries with intelligent file saving.

基于经纬度的天气与气候数据查询 MCP 服务器，支持智能文件保存到用户工作目录。

功能特性 / Features

$3

- 时间范围: 1940-01-01 至 D+14 (14天预报)
- 时间粒度: 5/15/30/60 分钟
- 数据类型:
- 天气预报 (温度、湿度、降水、风速、辐射等)
- 空气质量 (PM2.5, PM10, AQI, 臭氧等)
- 典型应用: 历史天气分析、短期预报、空气质量监测、光伏短期出力预测
- 文件保存: 自动保存到用户当前工作目录

$3

- 时间范围: 历史数据 至 未来50年
- 时间粒度: 按日 (daily)
- 数据类型: 日聚合值 (mean/max/min/sum)
- 典型应用: 长期气候规划、光伏/风电年发电量预测、农业分析、气候趋势研究
- 文件保存: 自动保存到用户当前工作目录

$3

- 查询时自动计算并展示费用
- 透明的费用计算规则
- 支持不同时间粒度和数据类型的成本评估

$3

- 不在对话中显示数据内容，保持对话简洁
- 只返回文件路径和费用信息
- 提升对话质量和响应速度

快速开始 / Quick Start

$3

无需安装，直接使用:

``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"
}
}
}
}
`

$3

`bash
npm install -g @xmo/weather-mcp
`

配置文件:

`json
{
"mcpServers": {
"weather-mcp": {
"command": "weather-mcp",
"env": {
"XMO_APIKEY": "your-api-key-here"
}
}
}
}
`

$3

点击查看 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 方式。


可用工具 / Available Tools

$3

核心特点:
- ✅ 自动计算并展示费用
- ✅ 直接查询，无需预估
- ✅ 智能场景识别

参数:
`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. 指定绝对路径: 使用指定的绝对路径

$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 文件路径（保存在用户当前工作目录）
- 查询参数摘要
- 自动展示费用

文件保存规则: 同天气数据

使用示例 / Examples

$3

`
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
`

$3

`
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
`

$3

`
User: 查询北京(116.4, 39.9)昨天的小时级空气质量数据

AI: (调用 query_weather_data，use_case="air_quality")
✅ 天气数据查询成功
💰 预估费用: 0.2 调用量
输出文件: 包含 PM2.5, PM10, AQI 等数据
`

$3

`
User: 给我(120, 30)从2025年1月1日到1月3日，30分钟间隔的温度和辐照度数据

AI: 理解需求，转换为:
- use_case: solar (因为提到了辐照度)
- freq: 30
调用 query_weather_data 获取数据
`

数据说明 / Data Description

$3

| 特性 | 天气数据 | 气候数据 |
|------|---------|---------|
| 时间粒度 | 5/15/30/60 分钟 | 按日 (daily) |
| 时间范围 | 1940 ~ D+14 | 历史 ~ 未来50年 |
| 主要用途 | 短期预报、实时监测 | 长期规划、趋势分析 |
| 数据类型 | 实时天气、空气质量 | 日聚合统计 |
| 典型场景 | 空气质量分析、短期光伏预测 | 年发电量预测、气候研究 |

$3

#### 天气数据费用
`python


等效天数

data_points = (end - start).total_minutes / freq
points_per_day = 24 * 60 / freq
equivalent_days = data_points / points_per_day

费用计算

time_weight = equivalent_days / 14.0
variables_weight = n_elements / 10.0
variable_time_weight = max(variables_weight, time_weight * variables_weight)
total_cost = ceil(max(1.0, variable_time_weight) n_locations) 0.2
`

示例: 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.csv

AI 会设置: 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.0

Node.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 之间
``
解决方案: 检查纬度 (-90 到 90) 和经度 (-180 到 180)

$3

解决方案:
1. 检查配置文件路径是否正确
2. 确认 Python 环境正确
3. 重启 MCP 客户端
4. 查看客户端日志

相关链接 / Links

- MCP Documentation
- 天气数据 API 文档
- 气候数据 API 文档

许可证 / License

MIT License

更新日志 / Changelog

$3

- 初始版本
- 支持天气数据查询 (1940~D+14)
- 支持气候数据查询 (历史~未来50年)
- 自动费用核算 - 查询时自动展示费用
- 智能文件保存 - 自动保存到用户当前工作目录
- 提供 2 个核心 MCP 工具
- 智能场景识别 (光伏/风电/空气质量/农业)
- 简洁输出 - 不在对话中显示数据内容，保持对话质量