QWeather

You can run the QWeather MCP Server to query real-time weather data, multi-day forecasts, air quality, and related indices through a unified Model Context Protocol interface. This server connects to QWeather API and exposes a range of weather-related tools that you can use from any MCP client to obtain structured weather information.

How to use

To use the QWeather MCP Server, start the local MCP process and then connect your MCP client to it. You will access a set of tools that return weather data for a specified location, including current conditions, forecasts for multiple days, hourly and minute-by-minute details, air quality, and life indices. Use the client’s standard MCP request flow to invoke the tools and receive structured results.

When you call a tool, specify the location (such as city name or coordinates) and, for forecast tools, the desired forecast horizon (3, 7, 10, 15, or 30 days). The server handles the API calls to QWeather and returns a consistent response you can consume in your application.

How to install

Prerequisites: You need Node.js installed on your machine. You will also use npm or npx to run the MCP server.

Start the MCP server using npm/npx as shown:

# stdio server
npx -y qweather-mcp

Configuration and startup details

Configure your QWeather API credentials and base URL to enable the server to reach the QWeather API.

QWEATHER_API_BASE=https://api.qweather.com
QWEATHER_API_KEY=<your-api-key>

JSON configuration example

You can also include the MCP server configuration in a JSON configuration file to start the server with your settings.

{
  "mcpServers": {
    "qweather": {
      "command": "npx",
      "args": ["-y", "qweather-mcp"],
      "env": {
        "QWEATHER_API_BASE": "https://api.qweather.com",
        "QWEATHER_API_KEY": "<your-api-key>"
      }
    }
  }
}

Notes on environment and security

Keep your API key secure. Do not expose your QWeather API key in client-side code or public repositories.

If you deploy the server in a production environment, consider restricting access to the MCP endpoints and rotating API keys periodically.

Tools and capabilities

The MCP server provides the following tools to query weather information.

• get-weather-now — Get current weather information for a specified location
• get-weather-forecast — Get weather forecast information for a location with 3/7/10/15/30 days
• get-minutely-precipitation — Minute-by-minute precipitation forecast for the next 2 hours
• get-hourly-forecast — Hourly weather forecasts for 24/72/168 hours
• get-weather-warning — Real-time weather warnings with details and recommendations
• get-weather-indices — Weather life indices such as UV, dressing, sports, etc.
• get-air-quality — Real-time air quality data
• get-air-quality-hourly — Hourly air quality forecast next 24 hours
• get-air-quality-daily — Daily air quality forecast next 3 days

Troubleshooting

If the server fails to start, verify that Node.js is installed and that you can access the QWeather API base URL. Check that the API key is correctly set and not expired.

Ensure that the environment variables are loaded in the runtime environment where the MCP process starts. If you change environment variables, restart the MCP server.

Available tools

get-weather-now

Get current weather information for a specified location.

get-weather-forecast

Get weather forecast information for a specified location with 3/7/10/15/30 days.

get-minutely-precipitation

Provide minute-by-minute precipitation forecast for the next 2 hours, including type and amount.

get-hourly-forecast

Provide hourly weather forecasts for 24, 72, or 168 hours with detailed conditions.

get-weather-warning

Provide real-time weather warning information with details and validity.

get-weather-indices

Provide weather life indices such as UV, dressing, sports, and other indices.

get-air-quality

Provide real-time air quality data including AQI and pollutants.

get-air-quality-hourly

Provide hourly air quality forecast for the next 24 hours.

get-air-quality-daily

Provide air quality forecast for the next 3 days.