Weather MCP Server

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

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

功能特性 / Features

1. 🌤️ 天气数据查询 (分钟/小时级)

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

2. 🌍 气候数据查询 (日级)

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

3. 💰 自动费用核算

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

4. ✨ 简洁输出

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

快速开始 / Quick Start

方式 1: npx 直接使用 (推荐)

无需安装，直接使用:

npx -y @xmo/weather-mcp

在 Claude Desktop 配置文件中添加 (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "weather-mcp": {
      "command": "npx",
      "args": ["-y", "@xmo/weather-mcp"],
      "env": {
        "XMO_APIKEY": "your-api-key-here"
      }
    }
  }
}

方式 2: 全局安装

npm install -g @xmo/weather-mcp

配置文件:

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

方式 3: Python 版本 (已弃用)

cd /Users/yuzuoyang/PycharmProjects/weather-mcp
pip install -e .

配置文件:

{
  "mcpServers": {
    "weather-mcp": {
      "command": "python",
      "args": ["/Users/yuzuoyang/PycharmProjects/weather-mcp/server.py"],
      "env": {
        "XMO_APIKEY": "your-api-key"
      }
    }
  }
}

注意: Node.js 版本更加方便且易于使用，推荐使用 npx 方式。

可用工具 / Available Tools

1. query_weather_data - 查询天气数据 (自动费用核算)

核心特点:

• ✅ 自动计算并展示费用
• ✅ 直接查询，无需预估
• ✅ 智能场景识别

参数:

{
  "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. 指定绝对路径: 使用指定的绝对路径

2. query_climate_data - 查询气候数据 (自动费用核算)

核心特点:

• ✅ 自动计算并展示费用
• ✅ 直接查询，无需预估
• ✅ 适用于长期规划

参数:

{
  "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

示例 1: 光伏场景 - 查询15分钟颗粒度天气数据

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

示例 2: 风电场景 - 查询未来一年气候数据

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 等数据

示例 4: 指定特定参数

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

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

数据说明 / Data Description

天气数据 vs 气候数据

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

费用计算规则

天气数据费用

# 等效天数
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 调用量

气候数据费用

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

保存位置

所有查询结果 CSV 文件自动保存到用户当前工作目录。

# 如果你在这个目录运行 Claude Desktop
/Users/yourname/projects/my-project/

# 那么文件会保存到
/Users/yourname/projects/my-project/weather_lat30.0_lon120.0_20260120_20260123.csv

文件命名规则

自动命名（未指定 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）

相对路径 - 相对于当前工作目录:

{
  "output_file": "data/solar_data.csv"
}
// 保存到: /Users/yourname/projects/my-project/data/solar_data.csv

绝对路径 - 直接使用指定路径:

{
  "output_file": "/Users/yourname/Downloads/weather.csv"
}
// 保存到: /Users/yourname/Downloads/weather.csv

仅文件名 - 保存到当前工作目录:

{
  "output_file": "my_weather.csv"
}
// 保存到: /Users/yourname/projects/my-project/my_weather.csv

使用示例

场景 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

Node.js 版本 (推荐)

• Node.js >= 18.0.0
• @modelcontextprotocol/sdk >= 0.5.0
• axios >= 1.6.0

Python 版本 (已弃用)

• 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

1. API Key 未设置

❌ 错误: XMO_APIKEY 环境变量未设置

解决方案: 设置环境变量 export XMO_APIKEY=your-api-key

2. 无效的时间间隔

❌ 错误: 时间间隔必须是 [5, 15, 30, 60] 之一

解决方案: 使用支持的频率值: 5, 15, 30, 或 60 分钟

3. 无效的坐标

❌ 错误: 纬度必须在 -90 到 90 之间

解决方案: 检查纬度 (-90 到 90) 和经度 (-180 到 180)

4. MCP 服务器未启动

解决方案:

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

相关链接 / Links

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

许可证 / License

MIT License

更新日志 / Changelog

v1.0.0 (2026-01-20)

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