io.github.overstarry/qweather-mcp

qweather-mcp

English | 简体中文

MCP server for QWeather API, providing comprehensive weather information query capabilities through Model Context Protocol (MCP).

✨ Features

• 🌤️ Real-time weather queries
• 📅 Multi-day weather forecasts (3/7/10/15/30 days)
• 🔐 JWT (EdDSA/Ed25519) and legacy API Key authentication
• 🔌 Custom API base URL support
• 🛠️ Complete tool integration

📦 Installation

Via Smithery

Recommended: Install automatically for Claude Desktop using Smithery:

npx -y @smithery/cli install @overstarry/qweather-mcp --client claude

Manual Configuration

1. First, get your credentials from the QWeather Console.
2. Start the server:

# stdio server
npx -y qweather-mcp

1. Configure environment variables (pick one of the two auth modes below).

🔐 JWT Authentication (recommended)

QWeather has announced that API Key authentication will be deprecated in 2027 and recommends migrating to JWT (EdDSA + Ed25519). Generate an Ed25519 key pair, upload the public key to the QWeather console, and configure:

QWEATHER_API_BASE=https://<your-host>.qweatherapi.com
QWEATHER_PROJECT_ID=<project-id>
QWEATHER_KEY_ID=<credential-id>
# Either pass the PEM path…
QWEATHER_PRIVATE_KEY_PATH=/path/to/ed25519-private.pem
# …or the PEM content directly (newlines preserved)
# QWEATHER_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"

If both QWEATHER_PRIVATE_KEY_PATH and QWEATHER_PRIVATE_KEY are provided, the path takes precedence. For QWEATHER_PRIVATE_KEY, the literal two-character sequence \n is auto-converted to real newlines, so the single-line form above works in shells, .env files, and JSON configs.

JSON config example:

{
  "mcpServers": {
    "qweather": {
      "command": "npx",
      "args": ["-y", "qweather-mcp"],
      "env": {
        "QWEATHER_API_BASE": "https://<your-host>.qweatherapi.com",
        "QWEATHER_PROJECT_ID": "<project-id>",
        "QWEATHER_KEY_ID": "<credential-id>",
        "QWEATHER_PRIVATE_KEY_PATH": "/path/to/ed25519-private.pem"
      }
    }
  }
}

JWT details: tokens are signed with alg=EdDSA, iat is back-dated 30s to tolerate clock skew, exp = iat + 900s (15 min, well under QWeather's 24h cap), and tokens are cached and reused until ~30s before expiry. See the official authentication docs.

🔑 API Key Authentication (legacy)

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

JSON config example:

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

Mode detection

The active mode is logged to stderr at startup, e.g. Weather MCP Server running on stdio (auth: JWT/EdDSA).

🛠️ 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 customizable forecast days:

• 3-day forecast
• 7-day forecast
• 10-day forecast
• 15-day forecast
• 30-day forecast

Forecast data includes:

• Temperature range (min/max)
• Day/night weather conditions
• Sunrise/sunset times
• Precipitation
• Humidity
• Wind conditions
• UV index

get-minutely-precipitation

Provides minute-by-minute precipitation forecast for the next 2 hours, including:

• Precipitation type (rain/snow)
• Precipitation amount per minute
• Precise time predictions
• Real-time forecast descriptions

get-hourly-forecast

Provides hourly weather forecasts for 24, 72, or 168 hours, including:

• Temperature changes
• Weather conditions
• Wind direction and force
• Relative humidity
• Atmospheric pressure
• Precipitation probability
• Cloud coverage

get-weather-warning

Provides real-time weather warning information, including:

• Warning issuing authority
• Warning level and type
• Detailed warning content
• Warning validity period
• Related recommendations

get-weather-indices

Provides weather life indices information, supporting various index types:

• Sports index
• Car wash index
• Dressing index
• Fishing index
• UV index
• Tourism index
• Allergy index and 16 other life indices

get-air-quality

Provides real-time air quality data, including:

• AQI index
• Air quality level
• Primary pollutants
• Health advice
• Pollutant concentrations

get-air-quality-hourly

Provides hourly air quality forecast for the next 24 hours:

• Hourly AQI predictions
• Pollutant concentration changes
• Health impact assessment
• Protection recommendations

get-air-quality-daily

Provides air quality forecast for the next 3 days:

• Daily AQI predictions
• Primary pollutant forecasts
• Air quality level changes
• Health protection advice

🤝 Contributing

Issues and improvements are welcome! Please check our contribution guidelines.

📄 License

MIT

🔗 Related Links

• QWeather Official Website
• API Documentation
• Console