qweather-mcp

May 10, 2026 · View on GitHub

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

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

# stdio server
npx -y qweather-mcp

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

Env vars present	Mode
Full JWT vars (`QWEATHER_PROJECT_ID` + `QWEATHER_KEY_ID` + `QWEATHER_PRIVATE_KEY[_PATH]`)	JWT (wins even if `QWEATHER_API_KEY` is also set)
Full JWT vars + `QWEATHER_API_KEY`	JWT (API Key is ignored)
Partial JWT vars + `QWEATHER_API_KEY`	API Key, with a startup warning to stderr
Partial JWT vars only	startup error
`QWEATHER_API_KEY` only	API Key
neither	startup error