Content
# Caiyun Weather MCP Server
[](https://smithery.ai/server/@marcusbai/caiyun-weather-mcp)
Model Context Protocol (MCP) server based on Caiyun Weather API, providing weather data query function.
## Features
- **Real-time weather data**: temperature, humidity, wind speed, air pressure, visibility, etc.
- **Minute-level precipitation forecast**: precipitation in the next 2 hours
- **Hourly weather forecast**: weather forecast for the next 24 hours or longer
- **Daily weather forecast**: weather forecast for the next few days
- **Weather warning information**: various weather warnings
- **Air quality trend**: 24-hour air quality change trend and analysis of main pollutants
- **Detailed life index**: detailed life suggestions for sports, travel, car washing, dressing, etc.
- **Precipitation type identification**: distinguish precipitation types such as rain, snow, sleet, and hail
- **Address query**: Supports querying weather by address, with built-in coordinate cache of 35 major cities, which can be used without additional configuration
- **Multi-language support**: Supports Chinese and English
- **Unit system selection**: Supports metric and imperial
## Installation
### Install Smithery
Install Caiyun Weather for Claude's desktop application through [Smithery](https://smithery.ai/server/@pepperai/caiyun-weather-mcp):
```bash
npm install @smithery/cli -g
smithery install @pepperai/caiyun-weather-mcp
```
### Use via NPX
You can run directly via NPX:
```bash
npx caiyun-weather-mcp --api-key=Your Caiyun Weather API Key
```
Or set environment variables:
```bash
CAIYUN_API_KEY=Your Key npx caiyun-weather-mcp
```
### Install from source code
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 usually provided by Claude or other MCP-enabled applications.
3. Build the project:
```bash
npm run build
```
## Configuration
Before use, you need to configure the Caiyun Weather API key. The address query function supports built-in city cache, and the Gaode Map API key is the recommended configuration.
### Caiyun Weather API Key
1. Visit [Caiyun Weather Developer Center](https://dashboard.caiyunapp.com/)
2. Register and log in to your account
3. Create an application and get the API key
### Gaode Map API Key (Recommended)
1. Visit [Gaode Open Platform](https://lbs.amap.com/)
2. Register and log in to your account
3. Create an application and get the API key, you need to enable the "Geocoding" service
> **💡 Tip**: The Gaode Map API key is the recommended configuration. The system has built-in coordinate cache of 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 built-in coordinate cache of 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**: `Shanghai`, `Shanghai City`
- **Detailed address**: `Shanghai Pudong New Area`, `Beijing Chaoyang District`
- **City alias**: `Magic City`→Shanghai, `Imperial City`→Beijing, `Goat City`→Guangzhou, `Peng City`→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 processing**: Unknown address returns Beijing coordinates and prompts for configuration
## Configure MCP Settings
Edit the MCP settings file and 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 Gaode Map 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 Gaode Map API Key (Recommended)"
},
"disabled": false,
"autoApprove": []
}
}
}
```
## Usage Examples
### Get weather information based on latitude and longitude
```
<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 based on address
```
<use_mcp_tool>
<server_name>caiyun-weather</server_name>
<tool_name>get_weather_by_address</tool_name>
<arguments>
{
"address": "上海市",
"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 minute-level 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 warning 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
### Common Parameters
- `longitude`: longitude
- `latitude`: latitude
- `address`: address (only for `get_weather_by_address`)
- `daily_steps`: number of daily forecast days (1-15, default 5)
- `hourly_steps`: number of hourly forecasts (1-360, default 24)
- `language`: language (`zh_CN` or `en_US`, default `zh_CN`)
- `unit`: unit system (`metric` or `imperial`, default `metric`)
## License
MIT
