qweather-mcp

English | 中文

A QWeather MCP server built on the official mcp SDK 2.x (MCPServer), with both stdio and streamable-http transports. Credentials stay in the server process — clients only ever pass a location parameter.

Tools

location accepts a city name, a LocationID, or "lon,lat" (e.g. "116.41,39.92"). Weather tools query by lat-lon via the v1 API (1 km resolution, global coverage); get_weather_report is generated from v1 daily forecast data. Only life indices still use the v7 endpoint (/v7/indices, no v1 equivalent).

Endpoint-to-docs mapping lives in docs/. Adding a new API = one method in client.py + one @mcp.tool() in server.py.

Configuration

Environment variables only (12-factor); no config file. CLI flags (--transport/--host/--port) only control how the server runs. A missing required variable fails at startup, naming exactly what's missing.

The private key never leaves the filesystem: no client config file, no LLM context. Only the host and the two non-secret IDs live in client configs.

Run

Install as a global tool:

uv tool install .

# stdio (default; local clients spawn it)
qweather-mcp

# streamable-http (deploy as a shared service; clients just point at a URL)
qweather-mcp --transport streamable-http --host 0.0.0.0 --port 8111

Reinstall after code changes: uv tool install --force .. For development, uv tool install -e . gives you edit-in-place behavior.

For quick development runs of streamable-http:

uv run qweather-mcp --transport streamable-http   # 127.0.0.1:8111/mcp by default

Client integration

Claude Code (.mcp.json):

{
  "mcpServers": {
    "qweather": {
      "command": "/Users/you/.local/bin/qweather-mcp",
      "env": {
        "QWEATHER_API_HOST": "<your dedicated API host>",
        "QWEATHER_PROJECT_ID": "<project ID>",
        "QWEATHER_CREDENTIAL_ID": "<credential ID>"
      }
    }
  }
}

Other MCP clients (Claude Desktop, Gemini, agents, …): the same command + the three env vars above in each client's MCP config.

Shared-service mode: run qweather-mcp --transport streamable-http --host 0.0.0.0 --port 8111, then register http://127.0.0.1:8111/mcp in any client that speaks streamable-http (e.g. LangChain/LangGraph load_mcp_tools). Network isolation (cluster-internal only) is recommended for deployments.

Container deployment: uv tool install . (or pip install) inside the image, run qweather-mcp --transport streamable-http; config all via container env, mount the private key as a secret and point QWEATHER_PRIVATE_KEY_PATH at it.

License

MIT