彩云天气 MCP Server

🌤️ 一个基于彩云天气 API v2.6的专业天气数据 MCP (Model Context Protocol) 服务器

彩云天气是中国领先的精准天气服务提供商，为用户提供高精度、多时效的专业气象数据服务。本MCP Server将彩云天气强大的API能力封装为标准化的MCP工具，让AI助手能够轻松获取和分析天气信息。

🎯 功能特性

核心能力

• 🌡️ 高精度数据: 基于多源气象数据融合，提供精准的天气信息
• 🕐 多时效预报: 从分钟级到15天的全时效天气预报覆盖
• 🌍 全域覆盖: 支持中国大陆任意经纬度位置的天气查询
• 🌐 多语言支持: 支持15种语言，包括中英日韩德法等主要语言
• 📏 灵活单位: 支持公制和英制单位制自由切换
• 🚨 官方预警: 基于中国气象局发布的权威气象灾害预警

🛠️ MCP工具清单

1️⃣ 实时天气 (get_realtime_weather)

获取当前精准天气状况，包含完整的气象要素：

• 🌡️ 温度、体感温度、湿度、云量
• 💨 风速、风向、气压、能见度
• 🌧️ 降水状况、降水强度
• 🫁 PM2.5/PM10/O3等空气质量指数
• 🌞 紫外线指数、舒适度指数

2️⃣ 分钟级降水预报 (get_minutely_precipitation)

精确到分钟的短临降水预测：

• ⏰ 未来120分钟逐分钟降水强度
• 📊 降水概率分析
• 🎯 基于雷达回波的高精度预测

3️⃣ 小时级预报 (get_hourly_forecast)

详细的逐小时天气演变：

• ⏳ 支持1-360小时(最长15天)预报
• 📈 逐小时温度、湿度、降水等要素变化
• 🌬️ 风力风向、气压、能见度趋势

4️⃣ 天级预报 (get_daily_forecast)

中长期天气趋势分析：

• 📅 支持1-15天预报范围
• 🌅 白天/夜晚天气现象区分
• 📊 每日最高/最低/平均值统计
• 🏃 生活指数：洗车、穿衣、感冒、紫外线等

5️⃣ 官方预警 (get_weather_alerts)

权威气象灾害预警信息：

• 🚨 台风、暴雨、暴雪、大风等预警
• 📍 精确到县级行政区划
• ⏰ 预警发布时间、更新时间
• 📝 详细预警描述和防护建议

6️⃣ 综合天气 (get_comprehensive_weather)

一站式完整天气信息：

• 🔄 整合实时、预报、预警于一体
• ⚡ 减少API调用次数，提升效率
• 🎛️ 支持所有参数自定义配置

安装

1. 克隆项目并安装依赖：

git clone <repository-url>
cd caiyun-mcp
npm install

2. 构建项目：

npm run build

3. 获取彩云天气 API 密钥：
   • 访问彩云科技开放平台
   • 注册账号并申请彩云天气 API 访问令牌
   • 完成开发者信息申请，等待审核通过

使用方法

环境变量配置

设置彩云天气 API 令牌：

export CAIYUN_API_TOKEN="your_api_token_here"

启动 MCP Server

npm start
# 或者直接运行
node dist/index.js

在 MCP 客户端中使用

配置你的 MCP 客户端连接到此 server。以下是各工具的使用示例：

1. 获取实时天气

{
  "tool": "get_realtime_weather",
  "arguments": {
    "longitude": 116.3176,
    "latitude": 39.976,
    "lang": "zh_CN",
    "unit": "metric:v2"
  }
}

2. 获取分钟级降水预报

{
  "tool": "get_minutely_precipitation",
  "arguments": {
    "longitude": 116.3176,
    "latitude": 39.976
  }
}

3. 获取小时级预报

{
  "tool": "get_hourly_forecast",
  "arguments": {
    "longitude": 116.3176,
    "latitude": 39.976,
    "hourlysteps": 48
  }
}

4. 获取天级预报

{
  "tool": "get_daily_forecast",
  "arguments": {
    "longitude": 116.3176,
    "latitude": 39.976,
    "dailysteps": 5
  }
}

5. 获取天气预警

{
  "tool": "get_weather_alerts",
  "arguments": {
    "longitude": 116.3176,
    "latitude": 39.976
  }
}

6. 获取综合天气信息

{
  "tool": "get_comprehensive_weather",
  "arguments": {
    "longitude": 116.3176,
    "latitude": 39.976,
    "hourlysteps": 48,
    "dailysteps": 5,
    "alert": true
  }
}

📋 参数详细说明

🎯 必需参数

📍 地理坐标 (基于WGS84坐标系)

• longitude (经度): -180° ~ +180°

  • 东经为正值，西经为负值
  • 中国范围：73°E ~ 135°E
  • 示例：北京 116.3176°E，上海 121.4737°E，广州 113.2644°E
  • 💡 建议精确到小数点后4位以获得最佳定位精度

• latitude (纬度): -90° ~ +90°

  • 北纬为正值，南纬为负值
  • 中国范围：18°N ~ 54°N
  • 示例：北京 39.9760°N，上海 31.2304°N，广州 23.1291°N
  • 💡 推荐使用GPS获取的高精度坐标

⚙️ 可选参数

🌐 语言设置 (lang)

支持15种语言，影响天气描述、地名、预警信息等的语言显示：

• zh_CN - 🇨🇳 简体中文 (默认)
• zh_TW - 🇭🇰 繁体中文
• en_US - 🇺🇸 美式英语
• en_GB - 🇬🇧 英式英语
• ja - 🇯🇵 日语
• de - 🇩🇪 德语
• fr - 🇫🇷 法语
• es - 🇪🇸 西班牙语
• it - 🇮🇹 意大利语
• ko - 🇰🇷 韩语
• ru - 🇷🇺 俄语
• hi - 🇮🇳 印地语
• th - 🇹🇭 泰语
• vi - 🇻🇳 越南语
• ar - 🇸🇦 阿拉伯语

📏 单位制设置 (unit)

• metric:v2 - 公制单位 (默认，推荐)
  • 温度: °C | 风速: km/h | 距离: km | 气压: Pa | 降水: mm/h
• imperial - 英制单位
  • 温度: °F | 风速: mph | 距离: mile | 气压: inHg | 降水: in/h
• metric - 旧版公制单位 (部分单位与v2不同)

⏰ 预报时长设置

• hourlysteps - 小时级预报步数 (1-360小时，默认48)

  • 24 = 1天 | 48 = 2天 | 72 = 3天 | 120 = 5天 | 240 = 10天 | 360 = 15天(最大)
  • 💡 较小值适合短期精准预报，较大值适合长期趋势分析

• dailysteps - 天级预报步数 (1-15天，默认5)

  • 1 = 今天 | 3 = 未来3天 | 5 = 未来5天 | 7 = 一周 | 15 = 最长预报
  • ⚠️ 预报时间越长，不确定性越大

🚨 预警开关 (alert)

• true (默认) - 包含气象预警信息
  • 返回当前生效的所有预警：台风、暴雨、暴雪、寒潮、大风、沙尘、高温、干旱等
  • 数据来源：中国气象局官方发布
• false - 不返回预警信息，减少数据量

📊 数据说明

🌤️ 天气现象代码 (Skycon)

彩云天气采用国际标准的天气现象分类，支持白天/夜晚区分：

🌞 晴朗天气

• CLEAR_DAY / CLEAR_NIGHT - 晴天/晴夜 (云量<10%)

☁️ 云量天气

• PARTLY_CLOUDY_DAY / PARTLY_CLOUDY_NIGHT - 多云 (云量10%-90%)
• CLOUDY - 阴天 (云量>90%)

🌧️ 降水天气

雨类 (按强度分级)：

• LIGHT_RAIN - 小雨 (0.1-2.5mm/h)
• MODERATE_RAIN - 中雨 (2.6-8.0mm/h)
• HEAVY_RAIN - 大雨 (8.1-15.9mm/h)
• STORM_RAIN - 暴雨 (≥16mm/h)

雪类 (按强度分级)：

• LIGHT_SNOW - 小雪 (0.1-2.5mm/h水当量)
• MODERATE_SNOW - 中雪 (2.6-5.0mm/h)
• HEAVY_SNOW - 大雪 (5.1-10mm/h)
• STORM_SNOW - 暴雪 (>10mm/h)

🌫️ 低能见度天气

• FOG - 雾 (水汽凝结，能见度<1km)
• LIGHT_HAZE - 轻雾霾 (能见度1-3km)
• MODERATE_HAZE - 中雾霾 (能见度0.5-1km)
• HEAVY_HAZE - 重雾霾 (能见度<0.5km)

🌪️ 特殊天气

• DUST - 浮尘 (远距离输送的细颗粒物)
• SAND - 沙尘暴 (强风卷起大量沙尘)
• WIND - 大风 (风力显著但无其他突出现象)

🫁 空气质量指数 (AQI)

提供双重标准的空气质量评估：

🇨🇳 中国标准 (CHN AQI)

• 0-50: 优 🟢 (空气质量令人满意)
• 51-100: 良 🟡 (可接受，敏感人群需注意)
• 101-150: 轻度污染 🟠 (敏感人群有症状)
• 151-200: 中度污染 🔴 (所有人群开始出现症状)
• 201-300: 重度污染 🟣 (健康警告)
• 300+: 严重污染 🟤 (紧急状况)

🇺🇸 美国标准 (USA AQI)

• 同样的6级分类，但计算方法和阈值略有不同
• 提供双语环境下的空气质量对比参考

🔬 污染物浓度

• PM2.5 - 细颗粒物 (μg/m³)
• PM10 - 可吸入颗粒物 (μg/m³)
• O3 - 臭氧浓度 (μg/m³)
• SO2 - 二氧化硫浓度 (μg/m³)
• NO2 - 二氧化氮浓度 (μg/m³)
• CO - 一氧化碳浓度 (mg/m³)

🏃 生活指数

基于气象条件计算的实用生活建议：

• 🌞 紫外线指数 - UV强度等级 (1-15级)，防晒建议
• 🚗 洗车指数 - 洗车时机建议，考虑降水概率
• 👔 穿衣指数 - 着装厚薄建议，基于体感温度
• 😌 舒适度指数 - 人体舒适感，综合温湿度评估
• 🤧 感冒指数 - 感冒易感性，基于温差湿度变化

💨 风力风向

• 风向: 16方位制 (N/NNE/NE/.../NNW)
• 风速: 支持km/h, mph等多种单位
• 风向角度: 0-360°，北为0°，顺时针增加

错误处理

Server 会自动处理以下错误情况：

• API 令牌未设置或无效
• 经纬度参数超出有效范围
• 网络连接失败
• 彩云天气 API 返回错误

所有错误都会以 MCP 标准错误格式返回，包含详细的错误描述。

📁 项目结构

本项目采用模块化架构，将功能按类型分为不同的模块：

src/
├── index.ts                    # MCP Server主入口
├── types.ts                    # TypeScript类型定义
├── tools/                      # 🛠️ 天气查询工具模块
│   ├── base.ts                 # 基础配置和接口
│   ├── index.ts                # 工具汇总导出
│   ├── realtime-weather.ts     # 实时天气
│   ├── minutely-precipitation.ts # 分钟级降水
│   ├── hourly-forecast.ts      # 小时级预报
│   ├── daily-forecast.ts       # 天级预报
│   ├── weather-alerts.ts       # 天气预警
│   └── comprehensive-weather.ts # 综合天气
├── prompts/                    # 💬 智能提示词系统
│   ├── index.ts                # 提示词系统入口
│   ├── base.ts                 # 基础架构和工具类
│   ├── knowledge.ts            # 知识类prompts(气象学、空气质量、预报)
│   ├── analysis.ts             # 分析类prompts(数据分析、生活指导)
│   ├── professional.ts         # 专业类prompts(行业服务、教育科普)  
│   ├── dynamic.ts              # 动态生成系统
│   ├── mcp-integration.ts      # MCP协议集成
│   └── README.md               # 系统详细说明
└── resources/                  # 📦 资源模块（预留）
    ├── index.ts                # 资源配置
    └── README.md               # 模块说明

🎯 模块化优势

• 🔧 易于维护: 每个工具独立文件，修改不互相影响
• 📈 可扩展性: 新增工具只需添加对应文件
• 👥 团队协作: 不同开发者可并行开发不同工具
• 🔄 代码复用: 公共配置统一管理，避免重复
• 📚 文档清晰: 每个模块都有明确的职责和说明
• 🧠 智能化: 完整的prompt系统，为AI提供丰富的气象知识

🧠 MCP Prompt 系统

本项目包含了完整的MCP Prompt系统，为AI提供专业的天气知识服务:

📚 知识体系

• 🌤️ 气象学专家: 深度解析天气现象和物理机制
• 🌫️ 空气质量专家: 专业的AQI分析和健康指导
• 🔮 预报技术专家: 天气预报原理和精度评估
• 📊 数据分析师: 专业的天气数据分析和解读
• 🏠 生活顾问: 个性化的生活天气指导
• 🏢 行业专家: 面向各行业的专业气象服务
• 🎓 教育专家: 生动的气象科普和教育内容

🤖 智能特色

• 动态生成: 基于实时天气数据自动生成分析内容
• 个性化: 根据用户特征和需求定制服务
• 多层次: 支持基础到专家级的不同深度服务
• 本土化: 专门针对彩云天气API和中国气象特点优化

详细信息请参考:

• 项目架构: ARCHITECTURE.md
• Prompt系统: MCP-PROMPTS.md

🔧 开发

开发模式

npm run dev

运行测试

npm test

类型检查

npm run typecheck

添加新工具

1. 在 src/tools/ 目录下创建新工具文件
2. 实现工具配置（参考现有工具文件）
3. 在 src/tools/index.ts 中导出新工具
4. 更新类型定义（如需要）

License

MIT License

🚀 应用场景

🏢 企业级应用

• 智慧城市管理: 城市气象监测、应急预案制定
• 农业生产: 农作物生长监测、灌溉决策支持
• 物流运输: 路线规划、运输安全评估
• 能源管理: 风电光伏发电预测、负荷预测
• 建筑工程: 施工天气窗口、安全风险评估

🏠 个人应用

• 出行规划: 旅游天气查询、通勤路线建议
• 健康生活: 运动时机选择、疾病预防提醒
• 日常决策: 穿衣搭配、洗车时机、户外活动安排

🤖 AI助手增强

• 智能问答: 为AI助手提供实时准确的天气数据支持
• 上下文感知: 基于天气情况提供个性化建议
• 多模态交互: 结合语音、文本、图像的天气信息服务

🎖️ 技术优势

🎯 数据精准度

• 多源数据融合: 结合气象观测站、卫星、雷达、数值预报模型
• 本土化优势: 专注中国天气特点，预报精度优于国外产品
• 实时更新: 数据更新频率高，保证信息时效性

⚡ 性能表现

• 低延迟响应: 平均响应时间<500ms
• 高并发支持: 稳定服务，支持大规模并发访问
• 可靠性保证: 99.9%+服务可用性，企业级稳定性

🔧 集成便利

• 标准化接口: 完全符合MCP协议规范
• 丰富文档: 详尽的API文档和示例代码
• 灵活配置: 支持多种参数组合，满足不同需求

⚠️ 使用限制与建议

📍 地理覆盖

• 主要支持: 中国大陆地区 (18°N-54°N, 73°E-135°E)
• 数据精度: 城市级精度最高，偏远地区精度略低
• 海外支持: 海外地区数据有限，建议使用其他气象服务

🔑 API配额

• 请访问彩云科技开放平台了解配额限制
• 建议根据使用频率选择合适的套餐方案
• 合理使用缓存机制，避免不必要的重复请求

💡 最佳实践

• 位置精度: 使用GPS坐标，精确到小数点后4位
• 缓存策略: 相同位置的数据可缓存5-10分钟
• 错误处理: 实现超时重试和降级机制
• 参数优化: 根据实际需求选择合适的预报步数

🤝 社区与支持

📚 学习资源

• 彩云天气 API 文档 - 官方API详细文档
• Model Context Protocol - MCP协议规范
• MCP TypeScript SDK - MCP开发工具包

🆘 技术支持

• API问题: 访问彩云科技开放平台获取技术支持
• MCP相关: 查阅MCP官方文档或社区论坛
• 项目Issues: 通过GitHub Issues报告问题和建议

🌟 贡献指南

欢迎为项目贡献代码、文档或建议：

1. Fork项目并创建特性分支
2. 提交代码并添加相应测试
3. 更新文档说明
4. 提交Pull Request

🌈 让AI助手拥有感知天气的能力

基于彩云天气API v2.6 | 遵循MCP标准 | 开源免费使用

为您的AI应用注入专业的天气数据服务能力 ☀️🌧️❄️