Content
# HK Climate and Weather MCP Server
[](https://github.com/hkopenai/hk-climate-mcp-server)
[](https://opensource.org/licenses/MIT)
This is an MCP server that provides access to climate and weather data through a FastMCP interface.
## Data Source
* Hong Kong Observatory
## Features
- Current weather: Get current weather observations from HKO (supports optional region parameter)
- 9-day forecast: Get extended weather forecast including general situation, daily forecasts, sea and soil temperatures
- Local weather forecast: Get short-term weather forecast with outlook
- Weather warnings: Get summary and detailed information about active weather warnings
- Special weather tips: Get important weather-related safety tips
## API Reference
### Current Weather
`get_current_weather(region: str = "Hong Kong Observatory") -> Dict`
- Get current weather observations for a specific region in Hong Kong
- Parameters:
- region: The region to get weather for (default: "Hong Kong Observatory")
- Returns:
- Dict containing:
- warning: Current weather warnings
- temperature: Current temperature in Celsius
- humidity: Current humidity percentage
- rainfall: Current rainfall in mm
### 9-Day Weather Forecast
`get_9_day_weather_forecast(lang: str = "en") -> Dict`
- Get the 9-day weather forecast for Hong Kong
- Parameters:
- lang: Language code (en/tc/sc, default: en)
- Returns:
- Dict containing:
- generalSituation: General weather situation
- weatherForecast: List of daily forecast dicts
- updateTime: Last update time
- seaTemp: Sea temperature info
- soilTemp: List of soil temperature info
### Local Weather Forecast
`get_local_weather_forecast(lang: str = "en") -> Dict`
- Get local weather forecast for Hong Kong
- Parameters:
- lang: Language code (en/tc/sc, default: en)
- Returns:
- Dict containing:
- forecastDesc: Forecast description
- outlook: Outlook forecast
- updateTime: Last update time
- forecastPeriod: Forecast period
- forecastDate: Forecast date
### Weather Warning Summary
`get_weather_warning_summary(lang: str = "en") -> Dict`
- Get weather warning summary for Hong Kong
- Parameters:
- lang: Language code (en/tc/sc, default: en)
- Returns:
- Dict containing:
- warningMessage: List of warning messages
- updateTime: Last update time
### Weather Warning Information
`get_weather_warning_info(lang: str = "en") -> Dict`
- Get detailed weather warning information
- Parameters:
- lang: Language code (en/tc/sc, default: en)
- Returns:
- Dict containing:
- warningStatement: Warning statement
- updateTime: Last update time
### Special Weather Tips
`get_special_weather_tips(lang: str = "en") -> Dict`
- Get special weather tips for Hong Kong
- Parameters:
- lang: Language code (en/tc/sc, default: en)
- Returns:
- Dict containing:
- specialWeatherTips: List of special weather tips
- updateTime: Last update time
### Visibility Data
`get_visibility(lang: str = "en") -> Dict`
- Get latest 10-minute mean visibility data for Hong Kong
- Parameters:
- lang: Language code (en/tc/sc, default: en)
- Returns:
- Dict containing visibility data with fields and data arrays
### Lightning Data
`get_lightning_data(lang: str = "en") -> Dict`
- Get cloud-to-ground and cloud-to-cloud lightning count data
- Parameters:
- lang: Language code (en/tc/sc, default: en)
- Returns:
- Dict containing lightning data with fields and data arrays
### Moon Times
`get_moon_times(year: int, month: Optional[int] = None, day: Optional[int] = None, lang: str = "en") -> Dict`
- Get times of moonrise, moon transit and moonset
- Parameters:
- year: Year (2018-2024)
- month: Optional month (1-12)
- day: Optional day (1-31)
- lang: Language code (en/tc/sc, default: en)
- Returns:
- Dict containing moon times data with fields and data arrays
### Hourly Tides
`get_hourly_tides(station: str, year: int, month: Optional[int] = None, day: Optional[int] = None, hour: Optional[int] = None, lang: str = "en") -> Dict`
- Get hourly heights of astronomical tides for a specific station
- Parameters:
- station: Station code (e.g. 'CCH' for Cheung Chau)
- year: Year (2022-2024)
- month: Optional month (1-12)
- day: Optional day (1-31)
- hour: Optional hour (1-24)
- lang: Language code (en/tc/sc, default: en)
- Returns:
- Dict containing tide data with fields and data arrays
### High/Low Tides
`get_high_low_tides(station: str, year: int, month: Optional[int] = None, day: Optional[int] = None, hour: Optional[int] = None, lang: str = "en") -> Dict`
- Get times and heights of astronomical high and low tides
- Parameters:
- station: Station code (e.g. 'CCH' for Cheung Chau)
- year: Year (2022-2024)
- month: Optional month (1-12)
- day: Optional day (1-31)
- hour: Optional hour (1-24)
- lang: Language code (en/tc/sc, default: en)
- Returns:
- Dict containing tide data with fields and data arrays
### Weather and Radiation Report
`get_weather_radiation_report(date: str, station: str, lang: str = "en") -> Dict`
- Get weather and radiation level report for Hong Kong
- Parameters:
- date: Mandatory date in YYYYMMDD format (e.g., 20250618)
- station: Mandatory station code (e.g., 'HKO' for Hong Kong Observatory)
- lang: Language code (en/tc/sc, default: en)
- Returns:
- Dict containing weather and radiation data or error message if parameters are invalid
### Station Codes
`get_radiation_station_codes() -> Dict`
- Get a list of station codes and their corresponding names for weather and radiation reports in Hong Kong
- Parameters:
- None
- Returns:
- Dict mapping station codes to station names
## Setup
1. Clone this repository
2. Install Python dependencies:
```bash
pip install -r requirements.txt
```
3. Run the server:
```bash
python server.py
```
### Running Options
- Default stdio mode: `python server.py`
- SSE mode (port 8000): `python server.py --sse`
### Environment Variables
- `TRANSPORT_MODE`: Set to `sse` to run the server in SSE mode. If not set, defaults to `stdio` mode.
- `HOST`: When `TRANSPORT_MODE` is `sse`, specifies the host to bind the server to (e.g., `0.0.0.0`). Defaults to `127.0.0.1`.
- `PORT`: When `TRANSPORT_MODE` is `sse`, specifies the port to run the server on (e.g., `8080`). Defaults to `8000`.
Example:
```bash
TRANSPORT_MODE=sse HOST=0.0.0.0 PORT=8080 python server.py
```
## Cline Integration
To connect this MCP server to Cline using stdio:
1. Add this configuration to your Cline MCP settings (cline_mcp_settings.json):
```json
{
"hko-server": {
"disabled": false,
"timeout": 3,
"type": "stdio",
"command": "python",
"args": [
"-m",
"hkopenai.hk_climate_mcp_server"
]
}
}
```
## Testing
Tests are available in `tests`. Run with:
```bash
pytest
