Caiyun Weather

You can query Caiyun Weather data through an MCP server, exposing real-time weather, forecasts, alerts, and city address support via a simple MCP interface. This guide shows practical steps to install, configure, and use the Caiyun Weather MCP server from your MCP client.

How to use

You will run an MCP client that communicates with the Caiyun Weather MCP server to fetch weather data. Use the available endpoints to retrieve real-time conditions, minute-by-minute precipitation forecasts, hourly and daily forecasts, weather warnings, air quality trends, and detailed life indices. You can query by geographic coordinates or by address, with built‑in city coordinates for quick starts.

How to install

Prerequisites you need before installing: node.js and npm installed on your system. You may also use NPX or a local build workflow if you prefer running the MCP server directly.

# Option 1: Install via Smithery (CLI) and use the MCP server in Claude
npm install @smithery/cli -g
smithery install caiyun-weather-mcp

# Option 2: Run directly with NPX (no install needed)
npx caiyun-weather-mcp --api-key=YOUR_CAiyun_API_KEY

# Or set the API key via environment variable
CAIYUN_API_KEY=YOUR_CAiyun_API_KEY npx caiyun-weather-mcp

# Option 3: From source (clone, install, build, run)
git clone https://github.com/marcusbai/caiyun-weather-mcp.git
cd caiyun-weather-mcp
npm install
npm run build
# Start the server after building
node path/to/caiyun-weather-mcp/dist/index.js

Configuration and usage notes

Configure your MCP settings to point to the Caiyun Weather MCP server. You have two standard local run options. The first uses a direct Node runtime to execute the built index, the second uses NPX to run the package on demand.

{
  "mcpServers": {
    "caiyun_weather": {
      "command": "node",
      "args": ["/path/to/caiyun-weather-mcp/dist/index.js"],
      "env": {
        "CAIYUN_API_KEY": "YOUR彩云天气API密钥",
        "AMAP_API_KEY": "YOUR高德地图API密钥（推荐）"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

{
  "mcpServers": {
    "caiyun_weather": {
      "command": "npx",
      "args": ["caiyun-weather-mcp"],
      "env": {
        "CAIYUN_API_KEY": "YOUR彩云天气API密钥",
        "AMAP_API_KEY": "YOUR高德地图API密钥（推荐）"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Additional notes

The service includes address-based weather lookup with built‑in coordinates for 35 major cities. If you enable the map service, you can resolve arbitrary addresses as well. Built‑in city coordinates provide fast start without extra configuration.

Tools and endpoints

The Caiyun Weather MCP server exposes a set of tools you can call from your MCP client. These tools cover retrieving weather data in various scopes and formats.

Available tools

get_weather_by_location

Fetches weather data using geographic coordinates, with options for daily and hourly steps and language/unit preferences.

get_weather_by_address

Resolves a textual address to coordinates (or uses cached city coordinates) and returns weather data for that location.

get_realtime_weather

Returns current weather conditions for a given location.

get_minutely_forecast

Provides minute-level precipitation forecast for the next moments.

get_hourly_forecast

Fetches hourly weather forecast across a specified number of hours.

get_daily_forecast

Fetches daily weather forecast across a specified number of days.

get_weather_alert

Retrieves active weather alerts for the given location.

get_air_quality_trend

Returns 24-hour air quality trend data and major pollutants analysis.

get_detailed_life_index

Provides detailed living indexes such as activity, travel, car wash, and clothing guidance.

get_weather_types

Distinguishes precipitation types like rain, snow, sleet, hail.