Skip to main content
Glama
nnsay

qweather-mcp

by nnsay
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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

Tool

Returns

Use case

lookup_city(location, adm?, country?, number?)

City list (id / lat-lon / admin region)

Geo: city search / coordinate lookup

get_top_cities(country?, number?)

Top cities list

Geo: top cities per country

lookup_poi(location, poi_type, city?, number?)

POI list

Geo: attractions / tide station search

lookup_poi_range(location, poi_type, radius?, number?)

POI list

Geo: POIs within a radius

get_current_weather(location, local_time?)

Nowcast JSON (city + v1 current)

Current weather (global lat-lon)

get_daily_forecast(location, days?, local_time?)

Forecast JSON (city + v1 days[])

Daily forecast (up to 10 days)

get_hourly_forecast(location, hours?, local_time?)

Forecast JSON (city + v1 hours[])

Hourly forecast (up to 240 hours)

get_minutely_precipitation(location)

City + summary + 5-min precipitation series

Minutely precipitation (China only, next 2 hours)

get_weather_indices(location, days?, types?)

City + indices list (with descriptions)

Life indices (1/3 days, optional types)

get_air_quality(location)

City + AQI + pollutants

Real-time air quality (with health advice)

get_air_quality_hourly(location)

City + hourly AQI/pollutants

Air quality hourly forecast (24h)

get_air_quality_daily(location)

City + daily AQI/pollutants

Air quality daily forecast (3d)

get_storm_list(year?, basin?)

Typhoon id / name / year / active

Typhoon list (last 2 years, NP basin)

get_storm_track(stormid)

Nowcast now + track track

Typhoon real-time and track

get_storm_forecast(stormid)

Forecast position / grade / pressure / wind

Typhoon forecast (active storms)

get_tide(location, date?)

High/low tides + hourly sea level

Tides (next 10 days)

get_sunrise_sunset(location, date?)

Sunrise / sunset times

Astronomy: sunrise & sunset (60 days)

get_moon(location, date?)

Moonrise / moonset + hourly phases

Astronomy: moonrise, moonset & phase (60 days)

get_solar_elevation_angle(location, time, date?, tz?, alt?)

Solar elevation / azimuth

Astronomy: solar elevation angle

get_weather_alerts(location, local_time?)

Active official warning list

Weather warnings (most countries worldwide)

get_weather_report(location)

Ready-to-send Markdown (today's overview + 3-day forecast + tips)

Push / notification scenarios

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.

Related MCP server: Weather MCP Server

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.

Variable

Description

QWEATHER_API_HOST

Your dedicated API host, e.g. your-host.re.qweatherapi.com (required)

QWEATHER_PROJECT_ID

Project ID, JWT sub (required)

QWEATHER_CREDENTIAL_ID

Credential ID, JWT kid (required)

QWEATHER_PRIVATE_KEY_PATH

Ed25519 private key path, default ~/.ssh/ed25519-private.pem

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Weather MCP Server

    ajayamal
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides weather forecasts and active alerts for US locations using the National Weather Service API. It supports both local stdio and remote HTTP/SSE transport modes for flexible integration with MCP clients.
    102 npm
    GPL 3.0

  • mcp-server

    keijumasukawa
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server that provides tools to retrieve weather information from a weather API, supporting both local stdio and remote Streamable HTTP transports.
    221 npm
    1
    MIT