Content
# Caiyun Weather MCP Server
[](https://smithery.ai/server/@marcusbai/caiyun-weather-mcp)
A Model Context Protocol (MCP) server based on the Caiyun Weather API, providing weather data query functionality.
## Features
- **Real-time Weather Data**: Temperature, humidity, wind speed, atmospheric pressure, visibility, etc.
- **Minute-level Precipitation Forecast**: Precipitation conditions for the next 2 hours
- **Hourly Weather Forecast**: Weather forecast for the next 24 hours or longer
- **Daily Weather Forecast**: Weather forecast for multiple days ahead
- **Weather Warning Information**: Various types of weather warnings
- **Air Quality Trends**: 24-hour air quality change trends and major pollutant analysis
- **Detailed Lifestyle Index**: Detailed lifestyle suggestions for exercise, travel, car washing, dressing, etc.
- **Precipitation Type Identification**: Distinguish between rain, snow, sleet, hail, and other types of precipitation
- **Address Query**: Supports weather queries by address, with built-in cache for coordinates of 35 major cities, ready to use without additional configuration
- **Multilingual Support**: Supports Chinese and English
- **Unit System Selection**: Supports metric and imperial systems
## Installation
### Installing Smithery
Install 彩云天气 (Caiyun Weather) for Claude's desktop application via [Smithery](https://smithery.ai/server/@pepperai/caiyun-weather-mcp):
```bash
npm install @smithery/cli -g
smithery install @pepperai/caiyun-weather-mcp
```
### Using NPX
You can run it directly via NPX:
```bash
npx caiyun-weather-mcp --api-key=Your Caiyun Weather API Key
```
Or set the environment variable:
```bash
CAIYUN_API_KEY=Your Key npx caiyun-weather-mcp
```
### Install from Source
1. Clone the repository:
```bash
git clone https://github.com/marcusbai/caiyun-weather-mcp.git
cd caiyun-weather-mcp
```
2. Install dependencies:
```bash
npm install
```
> **Note**: This project depends on the Model Context Protocol (MCP) SDK, which needs to be available in the runtime environment. The MCP SDK is typically provided by Claude or other applications that support MCP.
3. Build the project:
```bash
npm run build
```
## Configuration
Before use, it is necessary to configure the Caiyun Weather API key. The address query function supports built-in city caching, and the Gaode Map API key is recommended for configuration.
### Caiyun Weather API Key
1. Visit the [Caiyun Weather Developer Center](https://dashboard.caiyunapp.com/)
2. Register and log in to your account
3. Create an application and obtain the API key
### Amap API Key (Recommended)
1. Visit [Amap Open Platform](https://lbs.amap.com/)
2. Register and log in to your account
3. Create an application and obtain the API key, ensuring that the "Geocoding" service is enabled
> **💡 Tip**: The Amap API key is a recommended configuration. The system has a built-in cache of coordinates for 35 major cities, including all municipalities, provincial capitals, and economically developed cities, which can be used without additional configuration.
## Address Resolution Function
### Supported Cities
The system has a built-in cache of coordinates for the following 35 major cities:
**Municipalities**: Beijing, Shanghai, Tianjin, Chongqing
**Provincial Capitals and Major Cities**: Guangzhou, Shenzhen, Hangzhou, Nanjing, Wuhan, Chengdu, Xi'an, Changsha, Shenyang, Dalian, Qingdao, Xiamen, Suzhou, Zhengzhou, Jinan, Harbin, Shijiazhuang, Taiyuan, Hefei, Nanchang, Fuzhou, Nanning, Kunming, Guiyang, Lanzhou, Xining, Lhasa, Hohhot, Haikou, Yinchuan, Urumqi
### Intelligent Address Matching
Supports multiple address formats and intelligent matching:
- **Standard Format**: `上海`, `上海市`
- **Detailed Address**: `上海市浦东新区`, `北京市朝阳区`
- **City Aliases**: `魔都` → Shanghai, `帝都` → Beijing, `羊城` → Guangzhou, `鹏城` → Shenzhen, etc.
### Address Resolution Strategy
1. **Cache Priority**: Built-in city coordinates are returned immediately
2. **API Enhancement**: Supports any address after configuring Gaode API
3. **Degradation Handling**: Unknown addresses return Beijing coordinates and prompt for configuration
## Configure MCP Settings
Edit the MCP settings file to add the Caiyun Weather MCP server configuration:
```json
{
"mcpServers": {
"caiyun-weather": {
"command": "node",
"args": ["full/path/caiyun-weather-mcp/dist/index.js"],
"env": {
"CAIYUN_API_KEY": "Your Caiyun Weather API key",
"AMAP_API_KEY": "Your Amap API key (recommended)"
},
"disabled": false,
"autoApprove": []
}
}
}
```
If you installed this service via NPX, you can use the following configuration:
```json
{
"mcpServers": {
"caiyun-weather": {
"command": "npx",
"args": ["caiyun-weather-mcp"],
"env": {
"CAIYUN_API_KEY": "Your Caiyun Weather API key",
"AMAP_API_KEY": "Your Amap API key (recommended)"
},
"disabled": false,
"autoApprove": []
}
}
}
```
## Usage Example
### Get Weather Information by Longitude and Latitude
```
<use_mcp_tool>
<server_name>caiyun-weather</server_name>
<tool_name>get_weather_by_location</tool_name>
<arguments>
{
"longitude": 116.3976,
"latitude": 39.9075,
"daily_steps": 5,
"hourly_steps": 24,
"language": "zh_CN",
"unit": "metric"
}
</arguments>
</use_mcp_tool>
```
### Get Weather Information by Address
```
<use_mcp_tool>
<server_name>caiyun-weather</server_name>
<tool_name>get_weather_by_address</tool_name>
<arguments>
{
"address": "Shanghai",
"daily_steps": 5,
"hourly_steps": 24,
"language": "zh_CN",
"unit": "metric"
}
</arguments>
</use_mcp_tool>
```
### Get Real-time Weather Data
```
<use_mcp_tool>
<server_name>caiyun-weather</server_name>
<tool_name>get_realtime_weather</tool_name>
<arguments>
{
"longitude": 116.3976,
"latitude": 39.9075,
"language": "zh_CN",
"unit": "metric"
}
</arguments>
</use_mcp_tool>
```
### Get Minutely Precipitation Forecast
```
<use_mcp_tool>
<server_name>caiyun-weather</server_name>
<tool_name>get_minutely_forecast</tool_name>
<arguments>
{
"longitude": 116.3976,
"latitude": 39.9075,
"language": "zh_CN",
"unit": "metric"
}
</arguments>
</use_mcp_tool>
```
### Get Hourly Weather Forecast
```
<use_mcp_tool>
<server_name>caiyun-weather</server_name>
<tool_name>get_hourly_forecast</tool_name>
<arguments>
{
"longitude": 116.3976,
"latitude": 39.9075,
"hourly_steps": 24,
"language": "zh_CN",
"unit": "metric"
}
</arguments>
</use_mcp_tool>
```
### Get Daily Weather Forecast
```
<use_mcp_tool>
<server_name>caiyun-weather</server_name>
<tool_name>get_daily_forecast</tool_name>
<arguments>
{
"longitude": 116.3976,
"latitude": 39.9075,
"daily_steps": 5,
"language": "zh_CN",
"unit": "metric"
}
</arguments>
</use_mcp_tool>
```
### Get Weather Alert Information
```
<use_mcp_tool>
<server_name>caiyun-weather</server_name>
<tool_name>get_weather_alert</tool_name>
<arguments>
{
"longitude": 116.3976,
"latitude": 39.9075,
"language": "zh_CN",
"unit": "metric"
}
</arguments>
</use_mcp_tool>
```
### Get Air Quality Trend
```
<use_mcp_tool>
<server_name>caiyun-weather</server_name>
<tool_name>get_air_quality_trend</tool_name>
<arguments>
{
"longitude": 116.3976,
"latitude": 39.9075,
"language": "zh_CN",
"unit": "metric"
}
</arguments>
</use_mcp_tool>
```
### Get Detailed Life Index
```
<use_mcp_tool>
<server_name>caiyun-weather</server_name>
<tool_name>get_detailed_life_index</tool_name>
<arguments>
{
"longitude": 116.3976,
"latitude": 39.9075,
"language": "zh_CN",
"unit": "metric"
}
</arguments>
</use_mcp_tool>
```
## Parameter Description
### General Parameters
- `longitude`: Longitude
- `latitude`: Latitude
- `address`: Address (used only for `get_weather_by_address`)
- `daily_steps`: Number of days for daily forecast (1-15, default 5)
- `hourly_steps`: Number of hours for hourly forecast (1-360, default 24)
- `language`: Language (`zh_CN` or `en_US`, default `zh_CN`)
- `unit`: Measurement system (`metric` or `imperial`, default `metric`)
## License
MIT
