Content
# Tool List
A MCP Server based on Model Context Protocol (MCP) for weather services, providing multiple weather data query functions such as weather forecasts, weather warnings, air quality, historical data, and astronomical information.
## Features
- **Weather Forecast**: Get detailed weather forecasts for 3-30 days (supporting 3d/7d/10d/15d/30d)
- **GeoAPI Service**: Popular city queries, POI searches, and range search functions
- **Air Quality Extension**: Air quality hourly/daily forecasts, monitoring station pollutant data queries
- **Grid Weather**: High-resolution numerical forecast weather for any global coordinates (3-5 km resolution)
- **Weather Warning**: Query real-time weather disaster warnings
- **Life Index**: Get various life index forecasts, such as washing, dressing, colds, etc. (16 types of indexes)
- **Air Quality**: Get city air quality index (AQI) and main pollutant information
- **Hourly Forecast**: Get future 24/72/168 hours of hourly weather (temperature, weather conditions, wind force/speed/direction, relative humidity, air pressure, precipitation probability, dew point, cloud volume, etc.)
- **Real-time Weather**: Get near real-time weather (temperature, perceived temperature, wind, humidity, air pressure, precipitation, visibility, dew point, cloud volume, etc.)
- **Historical Data**: Get historical weather and air quality data (up to 10 days)
- **Astronomical Data**: Get sunrise/sunset times, moon phase and moonrise/moonset information
- **Minute-level Forecast**: Get 5-minute precipitation forecast for the next 2 hours
- **Dual Authentication Support**: Support API KEY and JWT + EdDSA digital signature authentication
- **Detailed Logs**: Complete operation logs and error handling
## Installation
```bash
uv tool install hefeng-qweather-mcp
```
Or install using pip:
```bash
pip install hefeng-qweather-mcp
```
```env
# Recommended configuration - API KEY authentication (simple and quick)
HEFENG_API_HOST=your API host address
HEFENG_API_KEY=your API KEY
# Alternative configuration - JWT digital signature authentication
# HEFENG_PROJECT_ID=your project ID
# HEFENG_KEY_ID=your credential ID
# HEFENG_PRIVATE_KEY_PATH=./ed25519-private.pem
# Optional: directly load key content for easy remote deployment
# HEFENG_PRIVATE_KEY=
```
## Usage
### Quick Start
1. **Configure environment variables**
```bash
# Copy and edit the configuration file
cp .env.example .env
# Fill in your weather API configuration
# Recommended to use API KEY authentication
```
2. **Start the server**
```bash
# STDIO mode (recommended for local development)
hefeng-qweather-mcp stdio
# HTTP mode (recommended for remote access)
hefeng-qweather-mcp http
```
### Running Modes
#### HTTP Mode
HTTP mode provides a Web API interface, suitable for remote access and web integration:
```bash
hefeng-qweather-mcp http
```
The server will run at `http://127.0.0.1:8000`, and the MCP endpoint is `http://127.0.0.1:8000/mcp`.
**VS Code configuration:**
```json
{
"servers": {
"hefeng-qweather-mcp": {
"url": "http://127.0.0.1:8000/mcp",
"type": "http"
}
},
"inputs": []
}
```
#### STDIO Mode
STDIO mode communicates through standard input and output, suitable for local development:
```bash
hefeng-qweather-mcp stdio
```
**VS Code configuration:**
```json
{
"servers": {
"hefeng-qweather-mcp": {
"type": "stdio",
"command": "hefeng-qweather-mcp stdio"
}
},
"inputs": []
}
```
**Running with uv:**
```json
{
"servers": {
"hefeng-qweather-mcp": {
"type": "stdio",
"command": "uvx hefeng-qweather-mcp stdio",
"envFile": "${workspaceFolder}/.env"
}
},
"inputs": []
}
```
### Managing the Server
#### Checking Running Status
```bash
# Check background processes
ps aux | grep hefeng-qweather-mcp
```
#### Stopping the Server
```bash
# Stop all modes
pkill -f hefeng-qweather-mcp
# Or stop separately
pkill -f "hefeng-qweather-mcp stdio"
pkill -f "hefeng-qweather-mcp http"
```
#### Verifying Configuration
After the service starts, you can verify the configuration is correct by:
1. **Checking log output** - Confirm the API host and authentication information are displayed correctly
2. **Testing in VS Code** - Use the MCP tool to query weather data
3. **Checking service status** - Ensure the service is running normally without errors
If you encounter configuration issues, please check:
- Environment variables are set correctly
- API KEY is valid and not expired
- Network connection is normal
### Usage Examples
#### Astronomical Data Query Example
```python
# Query today's sunrise/sunset time in Beijing
get_astronomy_sun("Beijing", "20251029")
# Result: Sunrise 06:40, Sunset 17:17
# Query Shanghai's moon phase information
get_astronomy_moon("Shanghai", "20251101")
# Result: Moonrise 13:24, Moonset 23:09, Moon phase: Waxing gibbous
# Use coordinates to query (any global location)
get_astronomy_sun("116.41,39.92", "20251029") # Beijing coordinates
get_astronomy_moon("121.47,31.23", "20251101") # Shanghai coordinates
# Query future date astronomical data
get_astronomy_sun("Guangzhou", "20251225") # Christmas
get_astronomy_moon("Shenzhen", "20260101") # New Year's Day
```
#### Multi-day Weather Forecast Example
```python
# Query different days of weather forecast
get_weather("Beijing", "3d") # 3-day forecast (default)
get_weather("Shanghai", "7d") # 7-day forecast
get_weather("Guangzhou", "15d") # 15-day forecast
get_weather("Shenzhen", "30d") # 30-day forecast
```
#### GeoAPI Function Example
```python
# Get popular city list
get_top_cities(10, "cn") # Get 10 popular Chinese cities
# POI keyword search (metric radius)
search_poi("116.41,39.92", "Forbidden City", "scenic", radius=10000)
# POI range search (kilometer radius)
search_poi_range("116.41,39.92", "scenic", radius=2) # 2 km range scenic spots
# Search restaurants and other types of POI
search_poi("Beijing", "hot pot", "scenic", radius=5000) # Beijing 5 km scenic spots
```
#### Air Quality Extension Function Example
```python
# Air quality hourly forecast
get_air_quality_hourly("39.92,116.41", "24h") # 24-hour hourly air quality
get_air_quality_hourly("39.92,116.41", "72h") # 72-hour hourly air quality
# Air quality daily forecast
get_air_quality_daily("39.92,116.41", "3d") # 3-day air quality forecast
# Monitoring station data query
get_air_quality_stations("P58911") # Query monitoring station P58911's pollutant data
get_air_quality_stations("P53763") # Query monitoring station P53763's pollutant data
```
### Available MCP Tools
Your MCP server provides the following weather query tools:
#### Basic Weather Tools
- **`get_weather_now`** - Get real-time weather data
- Parameters: `city` (city name) or `location` (location ID/coordinates)
- Returns: temperature, perceived temperature, weather conditions, humidity, air pressure, etc.
- **`get_weather`** - Get weather forecast
- Parameters: `city` (city name), `days` (forecast days: 3d/7d/10d/15d/30d, default 3d)
- Returns: daily weather details for the specified number of days
- **`get_hourly_weather`** - Get hourly weather forecast
- Parameters: `hours` (24h/72h/168h), `city` or `location`
- Returns: hourly temperature, weather, wind force, humidity, etc.
#### Air Quality Tools
- **`get_air_quality`** - Get real-time air quality
- Parameters: `city` (city name)
- Returns: AQI, pollutant concentration, health suggestions
- **`get_air_quality_history`** - Get historical air quality
- Parameters: `city` (city name), `days` (1-10 days)
- Returns: historical air quality data
#### Life Index Tools
- **`get_indices`** - Get life index forecast
- Parameters: `city` (city name), `days` (1d/3d), `index_types` (index type)
- Returns: 16 types of life indexes (exercise, washing, dressing, colds, etc.)
#### Warning and Astronomical Tools
- **`get_warning`** - Get weather warning information
- Parameters: `city` (city name)
- Returns: real-time weather disaster warnings
- **`get_astronomy_sun`** - Get sunrise/sunset time
- Parameters: `location` (city name/location ID/coordinates), `date` (yyyyMMdd format, supports up to 60 days)
- Returns: sunrise/sunset time (supports any global location)
- **`get_astronomy_moon`** - Get moon phase and moonrise/moonset information
- Parameters: `location` (city name/location ID/coordinates), `date` (yyyyMMdd format, supports up to 60 days)
- Returns: moonrise/moonset time, hourly moon phase data (including moon phase name, illumination degree)
#### Historical and Detailed Data Tools
- **`get_weather_history`** - Get historical weather data
- Parameters: `city` or `location`, `days` (1-10 days)
- Returns: historical weather data
- **`get_minutely_5m`** - Get minute-level precipitation forecast
- Parameters: `location` (coordinates or city name)
- Returns: 5-minute precipitation forecast for the next 2 hours
#### GeoAPI Tools (New)
- **`get_top_cities`** - Get popular city list
- Parameters: `number` (return quantity, default 10), `city_type` (city type: cn/world/overseas, default cn)
- Returns: popular city list, including ID, coordinates, time zone, etc.
- **`search_poi`** - POI keyword search
- Parameters: `location` (location), `keyword` (search keyword), `poi_type` (POI type: scenic/TSTA), `radius` (search radius, metric, 100-50000)
- Returns: searched point of interest list, including detailed location information
- **`search_poi_range`** - POI range search
- Parameters: `location` (center coordinates), `poi_type` (POI type: scenic/TSTA), `radius` (search radius, kilometer, 1-50)
- Returns: point of interest within the specified range, sorted by distance
#### Air Quality Extension Tools (New)
- **`get_air_quality_hourly`** - Get air quality hourly forecast
- Parameters: `location` (latitude, longitude coordinates), `hours` (forecast duration: 24h/72h/168h), `lang` (language, default zh)
- Returns: hourly air quality data, including AQI, pollutant concentration, health suggestions
- **`get_air_quality_daily`** - Get air quality daily forecast
- Parameters: `location` (latitude, longitude coordinates), `days` (forecast days: 3d), `lang` (language, default zh)
- Returns: daily air quality forecast, including AQI trend and main pollutants
- **`get_air_quality_stations`** - Get air quality monitoring station data
- Parameters: `station_id` (monitoring station ID, such as P58911), `lang` (language, default zh)
- Returns: monitoring station pollutant concentration data, including various pollutant real-time concentration values
#### Grid Weather Tools
- **`get_grid_weather_now`** - Get grid real-time weather data
- Parameters: `location` (longitude and latitude coordinates), `lang` (language, default zh), `unit` (unit, default m)
- Returns: high-resolution (3-5 km) real-time weather data, supporting any global coordinates
- **`get_grid_weather_daily`** - Get grid daily weather forecast
- Parameters: `location` (longitude and latitude coordinates), `lang` (language, default zh), `unit` (unit, default m)
- Returns: daily weather forecast of grid numerical model
- **`get_grid_weather_hourly`** - Get grid hourly weather forecast
- Parameters: `location` (longitude and latitude coordinates), `lang` (language, default zh), `unit` (unit, default m)
- Returns: hourly weather forecast of grid numerical model
## Prerequisites
- Python >= 3.11
- OpenSSL (used to generate key pairs)
- Weather API developer account
## Development
### 1. Clone Project
```bash
git clone https://github.com/fengyucn/hefeng-qweather-mcp.git
cd hefeng-qweather-mcp
```
### 2. Install Dependencies
Using pip:
```bash
pip install -e .
```
Or using uv (recommended):
```bash
uv sync
```
### 3. Get Weather API Configuration
#### Method 1: API KEY Authentication (Recommended)
1. Visit [Weather Console](https://console.qweather.com/project/)
2. Register/login
3. Create project and get **API KEY**
4. Copy configuration template file:
```bash
cp .env.example .env
```
1. Edit `.env` file:
```env
# API KEY authentication configuration
HEFENG_API_HOST=your API host address
HEFENG_API_KEY=your API KEY
```
#### Method 2: JWT Digital Signature Authentication (Alternative)
If you need to use JWT authentication:
1. Create project and record **Project ID** on Weather Console
2. Generate EdDSA key pair:
```bash
openssl genpkey -algorithm ED25519 -out ed25519-private.pem \
&& openssl pkey -pubout -in ed25519-private.pem > ed25519-public.pem
```
3. Create digital signature credentials, upload public key file
4. Configure `.env` file:
```env
# JWT authentication configuration
HEFENG_API_HOST=your API host address
HEFENG_PROJECT_ID=your project ID
HEFENG_KEY_ID=your credential ID
HEFENG_PRIVATE_KEY_PATH=./ed25519-private.pem
```
**Note:** We recommend using API KEY authentication, which is simpler to configure. JWT authentication is suitable for scenarios that require higher security.
### Development Guide
1. **Code style**: The project uses `ruff` for code formatting and inspection
2. **Type checking**: Use `mypy` for static type checking
3. **Testing**: Suggest adding corresponding unit tests for new features
4. **Documentation**: Ensure all new features have detailed docstring documentation
## Version History
### v0.5.0 (latest)
- ✅ Added GeoAPI service: popular city query, POI search and range search
- ✅ Added air quality extension: hourly/daily forecast, monitoring station pollutant data query
- ✅ POI search supports keyword and range modes, supports scenic and tide station types
- ✅ Air quality forecast supports 24/72/168 hour hourly forecast and 3-day daily forecast
- ✅ Monitoring station data provides real-time pollutant concentration values, supports precise monitoring station ID query
- ✅ Fix API parameter format and documentation inconsistency, unified parameter verification mechanism
### v0.4.0
- ✅ Added grid weather interface: high-resolution numerical weather query
- ✅ Supports real-time weather query for any global coordinates (3-5 km resolution)
- ✅ Added grid daily weather forecast and hourly weather forecast
- ✅ Based on numerical forecast model, provide precise coordinate weather data
- ✅ Complete multi-language support and unit selection function
### v0.3.0
- ✅ Added astronomical data interface: sunrise/sunset time and moon phase and moonrise/moonset
- ✅ Added minute-level precipitation forecast interface (next 2 hours, 5-minute)
- ✅ Supports multiple weather forecast duration: 3d/7d/10d/15d/30d
- ✅ Supports 24/72/168 hour hourly weather forecast
- ✅ Complete historical data query (weather and air quality, up to 10 days)
- ✅ Optimize authentication system, prefer API KEY authentication
- ✅ Complete error handling and logging
### v0.2.1
- Basic weather query function
- JWT digital signature authentication support
- Air quality query
- Life index query
## License
MIT License
## Contribution Guide
We welcome any form of contribution!
### Submit Issue
If you find a bug or have a feature suggestion:
1. Check existing issues to avoid duplication
2. Use clear title and detailed description
3. If it is bug report, include reproduction steps and environment information
## Related Links
- [Weather Official Website](https://www.qweather.com/)
- [Weather Developer Console](https://console.qweather.com/project/)
- [Weather API Documentation](https://dev.qweather.com/docs/api/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Changelog](./CHANGELOG.md)
## Contact
If you have questions or suggestions, please contact:
- 🐛 Issues: [GitHub Issues](https://github.com/fengyucn/hefeng-qweather-mcp/issues)
- 💬 Discussion: [GitHub Discussions](https://github.com/fengyucn/hefeng-qweather-mcp/discussions)
---
**Disclaimer**: This project is for learning and research only, please follow Weather API service terms and API usage specifications.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available