You run an MCP server that exposes HeWeather QWeather data through a Model Context Protocol interface, letting clients fetch forecasts, warnings, air quality, historical data, and astronomical information in a structured, scalable way.

How to use

You can connect to the server using either the HTTP API endpoint or the STDIO-based local interface. The HTTP mode provides a web API you can call from any environment, while STDIO runs locally and communicates over standard input/output, which is convenient for development and scripting.

Key capabilities you can access include: real-time weather, multi-day forecasts (3d/7d/10d/15d/30d), hourly and minutely data, air quality, alerts, life indices, historical data, astronomy, and grid-based weather data. You can also use authentication via API KEY or JWT with EdDSA signatures, depending on your security needs.

How to install

uv tool install hefeng-qweather-mcp

pip install hefeng-qweather-mcp

Configuration and running modes

# API KEY authentication (recommended)
HEFENG_API_HOST=your-api-host
HEFENG_API_KEY=your-api-key

# JWT authentication (alternative)
# HEFENG_PROJECT_ID=your-project-id
# HEFENG_KEY_ID=your-credential-id
# HEFENG_PRIVATE_KEY_PATH=./ed25519-private.pem
# HEFENG_PRIVATE_KEY=<optional-key-content>

Two runtime modes are available. Use the HTTP mode for remote access and Web API integration, or use STDIO mode for local development and scripting.

# HTTP mode (recommended for remote access)
hefeng-qweather-mcp http

The server will run at http://127.0.0.1:8000 with the MCP endpoint at http://127.0.0.1:8000/mcp.

STDIO mode (local development)

hefeng-qweather-mcp stdio

For development, you can also use UVX to run STDIO mode:
```bash
uvx hefeng-qweather-mcp stdio

If you use an environment file, reference it with the envFile option in your editor/runner configuration.

## Optional editor configurations

In your editor, you can configure an MCP client to connect to the HTTP endpoint or STDIO interface. Example VS Code configurations show the MCP URL for HTTP and a STDIO command for local development.

## Managing the server

Check running processes

ps aux | grep hefeng-qweather-mcp

```bash
# Stop all modes
pkill -f hefeng-qweather-mcp

# Stop specific modes
pkill -f "hefeng-qweather-mcp stdio"
pkill -f "hefeng-qweather-mcp http"

Usage examples

# Example usage patterns are shown in the tool references below. Use your MCP client to query weather now, forecasts, air quality, astronomy, and more.

Tools and endpoints you can use

The server provides a comprehensive set of tools to query weather and related data, including real-time weather, multi-day forecasts, hourly/detailed forecasts, air quality, historical data, astronomy, and GeoAPI features.

Notes on security and logs

You can choose API KEY authentication for simplicity or JWT + EdDSA for stronger security. Detailed operation logs and error handling are available to help you troubleshoot and tune requests.

Examples by capability

# Example tool names you can call via MCP client:
get_weather_now
get_weather
get_hourly_weather
get_air_quality
get_air_quality_history
get_indices
get_warning
get_astronomy_sun
get_astronomy_moon
get_weather_history
get_minutely_5m
get_top_cities
search_poi
search_poi_range
get_air_quality_hourly
get_air_quality_daily
get_air_quality_stations
get_grid_weather_now
get_grid_weather_daily
get_grid_weather_hourly

架构与依赖

This server is designed to run with Python 3.11+ and relies on OpenSSL for key generation. You’ll manage configuration via environment variables and can run in STDIO or HTTP mode depending on your deployment needs.

Available tools

get_weather_now

Fetches real-time weather data for a city or location, including temperature, feels-like temperature, conditions, humidity, and pressure.

get_weather

Retrieves weather forecasts for a city for a specified horizon (3d/7d/10d/15d/30d) with daily details.

get_hourly_weather

Returns future hourly forecast data for the next 24/72/168 hours, including temperature, conditions, wind, humidity, etc.

get_air_quality

Gets real-time air quality index and pollutant concentrations for a city.

get_air_quality_history

Provides historical air quality data for a city over a period of 1-10 days.

get_indices

Fetches various life indices forecasts such as dressing, car wash, athletics, and more (16 indices).

get_warning

Retrieves real-time meteorological disaster warnings for a city.

get_astronomy_sun

Returns sunrise and sunset times for a location/date (up to 60 days forward).

get_astronomy_moon

Returns moonrise/moonset and hourly moon phase data for a location/date (up to 60 days forward).

get_weather_history

Queries historical weather data for a city/location over 1-10 days.

get_minutely_5m

Provides minute-level precipitation forecasts for the next 2 hours 5 minutes.

get_top_cities

Fetches a list of popular cities with IDs, coordinates, and time zones.

search_poi

POI keyword search by location, keyword, and type with a radius in meters.

search_poi_range

POI search within a radius in kilometers for a given location and type.

get_air_quality_hourly

Hourly air quality forecast for a location (24h/72h/168h) with AQI and pollutants.

get_air_quality_daily

Daily air quality forecast for a location with AQI trends and major pollutants.

get_air_quality_stations

Pollutant concentrations from a specified air quality monitoring station.

get_grid_weather_now

High-resolution grid-based real-time weather data for any global coordinates.

get_grid_weather_daily

Grid-based daily weather forecasts for a given coordinate.

get_grid_weather_hourly

Grid-based hourly weather forecasts for a given coordinate.