mcp-hko
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-hko what's the current weather in Hong Kong?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-hko (Hong Kong Observatory MCP Server)
This MCP server provides access to Hong Kong Observatory weather data APIs. It implements various tools that allow clients to retrieve weather forecasts, earthquake information, tide data, and other meteorological information through the Model Context Protocol.
Available Weather Data Tools
9-day Weather Forecast (fnd)
Current Weather Report (rhrread)
Local Weather Forecast (flw)
Weather Warning Information (warningInfo)
Weather Warning Summary (warnsum)
Special Weather Tips (swt)
Quick Earthquake Messages (qem)
Locally Felt Earth Tremor Report (feltearthquake)
Tide Information (HHOT, HLT)
Astronomical Data (SRS, lunardate)
Lightning and Visibility Data (LHL, LTMV)
Temperature Records (CLMTEMP, CLMMAXT, CLMMINT)
Radiation Level Reports (RYES)
Rainfall Data (hourlyrainfall)
Related MCP server: mcp-cwa
Usage Examples
Get 9-day weather forecast
prompt:
what is the weather in next Wed ?
Get current weather report
prompt:
what is the weather now ?
Development Setup
Install dependencies:
npm installStart the MCP development server:
npm run inspectBuild the MCP server:
npm run buildRun tests:
npm testRun tests in watch mode:
npm run test:watchComprehensive tests have been created for all API functions. See docs/TESTING.md for details.
Configuration (Claude Desktop)
{
"mcpServers": {
"mcp-hko": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"github:louiscklaw/mcp-hko"
]
}
}
}Configuration (docker)
{
"mcpServers": {
"mcp-hko-docker": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp-hko:latest"],
"name": "mcp-hko (Docker)",
}
}
}Project Structure
src/- Server source codesrc/lib/- API implementation modulesdocumentation/- API documentation and test casesscripts/- Development utilitiessrc/tests/- Test files
Server Architecture
The MCP server is built on the FastMCP framework and implements various tools that correspond to Hong Kong Observatory APIs. The architecture is shown in two diagrams for better readability:
Server Overview
Detailed Tool Structure
REQ01xx: Weather Forecasts & Warnings
flowchart TD
subgraph REQ01xx[Weather Forecasts & Warnings]
direction BT
B1[9-day Forecast]
B2[Current Weather]
B3[Local Forecast]
B4[Warning Info]
B5[Warning Summary]
B6[Special Weather Tips]
endREQ02xx: Earthquake Information
flowchart TD
subgraph REQ02xx[Earthquake Information]
C1[Quick Earthquake]
C2[Felt Earthquake]
endREQ03xx: Tides, Astronomy & Climate
flowchart TD
subgraph REQ03xx[Tides, Astronomy & Climate]
D1[Tide: HHOT]
D2[Tide: HLT]
D3[Sunrise/Sunset: SRS]
D4[Lightning: LHL]
D5[Visibility: LTMV]
D6[Temperature: CLMTEMP]
D7[Max Temperature: CLMMAXT]
D8[Min Temperature: CLMMINT]
D9[Radiation: RYES]
endREQ04xx: Lunar Calendar
flowchart TD
subgraph REQ04xx[Lunar Calendar]
E1[Lunar Date]
endREQ05xx: Rainfall
flowchart TD
subgraph REQ05xx[Rainfall]
F1[Hourly Rainfall]
endCredits:
Available Tools
20 toolsclmmaxtA
Daily Maximum Temperature (CLMMAXT) API Request
Parameters:
station: Station code (refer to documentation for full list)
year: Year (1884 - current year, station-specific range)
month: Month (1-12, optional but requires year)
rformat: 'json' or 'csv' (Response format, default: csv)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/opendata.php?dataType=CLMMAXT&station=HKO&year=2025&rformat=json
Response Keys (JSON format):
type: Array with data type ["Max Temperature"]
fields: Array with field names ["Year", "Month", "Day", "Temperature(C)"]
data: Array of arrays with temperature data
legend: Array with station information
Response Keys (CSV format):
Type: Data type line
Header row: Year,Month,Day,Temperature(C)
Data rows: Actual temperature data
Inputs: station (required), year (required), month, rformat.
clmminB
Daily Minimum Temperature (CLMMINT) API Request
Parameters:
station: Station code (refer to documentation for full list)
year: Year (1884 - current year, station-specific range)
month: Month (1-12, optional but requires year)
rformat: 'json' or 'csv' (Response format, default: csv)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/opendata.php?dataType=CLMMINT&station=HKO&year=2025&rformat=json
Response Keys (JSON format):
type: Array with data type ["Min Temperature"]
fields: Array with field names ["Year", "Month", "Day", "Temperature(C)"]
data: Array of arrays with temperature data
legend: Array with station information
Response Keys (CSV format):
Type: Data type line
Header row: Year,Month,Day,Temperature(C)
Data rows: Actual temperature data
Inputs: station (required), year (required), month, rformat.
clmtempB
Daily Mean Temperature (CLMTEMP) API Request
Parameters:
station: Station code (refer to documentation for full list)
year: Year (1884 - current year, station-specific range)
month: Month (1-12, optional but requires year)
rformat: 'json' or 'csv' (Response format, default: csv)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/opendata.php?dataType=CLMTEMP&station=HKO&year=2025&rformat=json
Response Keys (JSON format):
type: Array with data type ["Mean Temperature"]
fields: Array with field names ["Year", "Month", "Day", "Temperature(C)"]
data: Array of arrays with temperature data
legend: Array with station information
Response Keys (CSV format):
Type: Data type line
Header row: Year,Month,Day,Temperature(C)
Data rows: Actual temperature data
Inputs: station (required), year (required), month, rformat.
feltearthquakeB
Locally Felt Earth Tremor Report (feltearthquake) API Request
Parameters:
lang: 'en' (English), 'tc' (Traditional Chinese), 'sc' (Simplified Chinese)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/earthquake.php?dataType=feltearthquake&lang=en
Response Keys:
updateTime: Last update time (YYYY-MM-DD'T'hh:mm:ssZ)
mag: Richter magnitude scale (Numeric value)
region: Region of the earthquake (Text)
intensity: Intensity of the earthquake (Text)
lat: Latitude (Numeric value)
lon: Longitude (Numeric value)
details: Earthquake details (Text)
ptime: Date and time of the earthquake (YYYY-MM-DD'T'hh:mm:ssZ)
Inputs: lang.
flwB
Local Weather Forecast (flw) API Request
Parameters:
lang: 'en' (English), 'tc' (Traditional Chinese), 'sc' (Simplified Chinese)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=flw&lang=en
Response Keys:
generalSituation: General weather situation
tcInfo: Tropical cyclone information
fireDangerWarning: Fire danger warning message
forecastPeriod: Forecast period
forecastDesc: Detailed forecast description
outlook: Weather outlook
updateTime: Update time in format YYYY-MM-DD'T'hh:mm:ssZ
Inputs: lang.
fndB
9-day Weather Forecast (fnd) API Request
Parameters:
lang: 'en' (English), 'tc' (Traditional Chinese), 'sc' (Simplified Chinese)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=fnd&lang=en
Response Keys:
weatherForecast: List of daily forecasts
forecastDate: Forecast Date (YYYYMMDD)
forecastWeather: Forecast Weather
forecastMaxtemp: Forecast Maximum Temperature
forecastMintemp: Forecast Minimum Temperature
week: Day of the week
forecastWind: Wind direction and strength
forecastMaxrh: Maximum relative humidity
forecastMinrh: Minimum relative humidity
ForecastIcon: Weather icon code
PSR: Probability of Significant Rain (High, Medium High, Medium, Medium Low, Low)
Inputs: lang.
hhhotA
Hourly Heights of Astronomical Tides (HHOT) API Request
Parameters:
station: CCH/CLK/CMW/KCT/KLW/LOP/MWC/QUB/SPW/TAO/TBT/TMW/TPK/WAG
year: 2022-2024
month: (Optional) 1-12
day: (Optional) 1-31
hour: (Optional) 0-23
rformat: 'json' (Response format)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/opendata.php?dataType=HHOT&station=CCH&year=2025&rformat=json
Response Keys (JSON format):
type: Array with data type ["Hourly Heights of Astronomical Tides"]
fields: Array with field names ["Year", "Month", "Day", "Hour", "Height(m)"]
data: Array of arrays with tide data
legend: Array with station information
Response Keys (CSV format):
Type: Data type line
Header row: Year,Month,Day,Hour,Height(m)
Data rows: Actual tide data
Inputs: station (required), year (required), month, day, +2 more.
hltA
Times and Heights of Astronomical High and Low Tides (HLT) API Request
Parameters:
station: CCH/CLK/CMW/KCT/KLW/LOP/MWC/QUB/SPW/TAO/TBT/TMW/TPK/WAG
year: 2022-current year+1
month: (Optional) 1-12
day: (Optional) 1-31
hour: (Optional) 1-24
rformat: 'json' or 'csv' (Response format, default: json)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/opendata.php?dataType=HLT&station=CLK&year=2025&rformat=json
Response Keys (JSON format):
fields: Array with field names ["Date", "Time", "Height(m)", "Type"]
data: Array of arrays with tide data
Response Keys (CSV format):
Header row: Date,Time,Height(m),Type
Data rows: Actual tide data
Inputs: station (required), year (required), month, day, +2 more.
hourlyrainfallA
Rainfall in the Past Hour from Automatic Weather Station API Request
Parameters:
lang: Language option (en, tc, sc) - default: en
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/hourlyRainfall.php?lang=en
Response Keys:
obsTime: Observation time in ISO 8601 format
hourlyRainfall: Array of rainfall data from automatic weather stations
automaticWeatherStation: Name of the weather station
automaticWeatherStationID: ID of the weather station
value: Rainfall amount
unit: Measurement unit (mm)
Response example: { "obsTime": "2025-01-01T08:00:00+08:00", "hourlyRainfall": [ { "automaticWeatherStation": "Lau Fau Shan", "automaticWeatherStationID": "RF001", "value": "0", "unit": "mm" }, { "automaticWeatherStation": "Wetland Park", "automaticWeatherStationID": "RF002", "value": "2", "unit": "mm" } ] }
Inputs: lang.
lhlB
Cloud-to-Ground and Cloud-to-Cloud Lightning Count (LHL) API Request
Parameters:
lang: 'en', 'tc', or 'sc' (Language option, default: en)
rformat: 'json' or 'csv' (Response format, default: csv)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/opendata.php?dataType=LHL&lang=en&rformat=json
Response Keys (JSON format):
fields: Array with field names ["Date", "Time", "CloudToGround", "CloudToCloud"]
data: Array of arrays with lightning count data
Response Keys (CSV format):
Header row: Date,Time,CloudToGround,CloudToCloud
Data rows: Actual lightning count data
Inputs: lang, rformat.
ltmvA
Latest 10-minute Mean Visibility (LTMV) API Request
Parameters:
lang: 'en', 'tc', or 'sc' (Language option, default: en)
rformat: 'json' or 'csv' (Response format, default: csv)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/opendata.php?dataType=LTMV&lang=en&rformat=json
Response Keys (JSON format):
type: Array with data type ["10-minute Visibility"]
fields: Array with field names ["Automatic Weather Station", "Mean Visibility (km)"]
data: Array of arrays with visibility data
legend: Array with station information
Response Keys (CSV format):
Type: Data type line
Header row: Automatic Weather Station,Mean Visibility (km)
Data rows: Actual visibility data
Inputs: lang, rformat.
lunardateA
Gregorian-Lunar Calendar Conversion API Request
Parameters:
date: Gregorian date to convert (YYYY-MM-DD format)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/lunardate.php?date=2025-07-26
Response Keys:
LunarYear: Lunar year in traditional Chinese with zodiac (e.g. "癸卯年,兔")
LunarDate: Lunar date in traditional Chinese (e.g. "六月初二")
Inputs: date (required).
mrsC
Times of Moonrise/Moonset (MRS) API Request
Parameters:
dataType: 'MRS' (for Moonrise/Moonset Times)
rformat: 'json' or 'csv' (Response format, default: csv)
year: 2018-2024
month: (Optional) 1-12 (requires year)
day: (Optional) 1-31 (requires year and month)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/opendata.php?dataType=MRS&year=2025&month=1&rformat=json
Inputs: year, month, day, rformat.
qemB
Quick Earthquake Messages (qem) API Request
Parameters:
lang: 'en' (English), 'tc' (Traditional Chinese), 'sc' (Simplified Chinese)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/earthquake.php?dataType=qem&lang=en
Response Keys:
lat: Latitude
lon: Longitude
mag: Richter magnitude scale
region: Region
ptime: Earthquake date and time (YYYY-MM-DD'T'hh:mm:ssZ)
updateTime: Update time (YYYY-MM-DD'T'hh:mm:ssZ)
Inputs: lang.
rhrreadB
Current Weather Report (rhrread) API Request
Parameters:
lang: 'en' (English), 'tc' (Traditional Chinese), 'sc' (Simplified Chinese)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=rhrread&lang=en
Response Keys:
humidity: Current humidity data
temperature: Current temperature data
pressure: Current pressure data
wind: Current wind data
uvindex: Current UV index data
visibility: Current visibility data
rainfall: Current rainfall data
specialWxTips: Special weather tips
updateTime: Last update time
warningMessage: Weather warning messages
Inputs: lang.
ryesA
Weather and Radiation Level Report (RYES) API Request
Parameters:
date: Date of report (YYYYMMDD format)
lang: 'en', 'tc', or 'sc' (Language option, default: en)
station: Station code (refer to documentation for full list)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/opendata.php?dataType=RYES&date=20250101&lang=en&station=HKO
Response Keys:
type: Data type ("data")
SolarData: Solar radiation data with unit and period-value pairs
AmbientTemp: Ambient temperature data with unit and period-value pairs
Other parameters: Additional weather parameters
Inputs: date (required), station (required), lang.
srsA
Times of Sunrise/Sunset (SRS) API Request
Parameters:
year: 2018-2024
month: (Optional) 1-12 (requires year)
day: (Optional) 1-31 (requires year and month)
rformat: 'json' or 'csv' (Response format, default: csv)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/opendata.php?dataType=SRS&year=2025&month=1&rformat=json
Response Keys (JSON format):
type: Array with data type ["Sunrise/Sunset Times"]
fields: Array with field names ["Year", "Month", "Day", "Sunrise", "Sunset"]
data: Array of arrays with sunrise/sunset data
legend: Array with information
Response Keys (CSV format):
Type: Data type line
Header row: Year,Month,Day,Sunrise,Sunset
Data rows: Actual sunrise/sunset data
Inputs: year (required), month, day, rformat.
swtC
Special Weather Tips (swt) API Request
Parameters:
lang: 'en' (English), 'tc' (Traditional Chinese), 'sc' (Simplified Chinese)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=swt&lang=en
Response Keys:
desc: Tips Content
updateTime: Tips Update Time (YYYY-MM-DD'T'hh:mm:ssZ)
Inputs: lang.
warningInfoB
Weather Warning Information (warningInfo) API Request
Parameters:
lang: 'en' (English), 'tc' (Traditional Chinese), 'sc' (Simplified Chinese)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=warningInfo&lang=en
Response Keys:
Warning_Summary: Array of warning summary objects
Special_Warning: Array of special warning objects (if any)
Reminder_Warning: Array of reminder warning objects (if any)
Inputs: lang.
warnsumB
Weather Warning Summary (warnsum) API Request
Parameters:
lang: 'en' (English), 'tc' (Traditional Chinese), 'sc' (Simplified Chinese)
Request Example: https://data.weather.gov.hk/weatherAPI/opendata/weather.php?dataType=warnsum&lang=en
Response Keys:
{Property name}: Warning Statement Code (WFIRE, WFROST, WHOT, etc.)
name: Warning Name
code: Warning Code
actionCode: Action Code (ISSUE, REISSUE, CANCEL, etc.)
issueTime: Issue Time (YYYY-MM-DD'T'hh:mm:ssZ)
updateTime: Update Time (YYYY-MM-DD'T'hh:mm:ssZ)
Inputs: lang.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool has a clearly distinct purpose, covering different weather data types (temperature records, forecasts, tides, earthquakes, etc.). Descriptions are detailed enough to avoid confusion, even where tools seem related (e.g., flw vs fnd, warningInfo vs warnsum).
Tool names are inconsistent: some are cryptic abbreviations (e.g., flw, fnd, lhl, mrs, qem), others are longer descriptive names (e.g., hourlyrainfall, lunardate, warningInfo), and casing is mixed (all lowercase vs camelCase). No predictable pattern like verb_noun.
With 20 tools, the server covers a wide range of weather and astronomical data. While slightly on the high side, each tool serves a specific purpose for a national meteorological service. Could potentially consolidate a few, but the count is reasonable.
The server provides comprehensive coverage of current weather, forecasts, warnings, and historical temperature data. However, it lacks tools for historical rainfall, pressure, or wind data, which would be expected for full completeness. Still, the core functions are well-covered.
Maintenance
Related MCP Connectors
US weather & geo for AI agents: forecasts, alerts, earthquakes, elevation, geocoding. No keys.
US weather & geo for AI agents: forecasts, alerts, earthquakes, elevation, geocoding. No keys.
Global weather via Open-Meteo: forecast, historical, marine, air quality, geocoding, elevation.
US NWS weather alerts and 5-day forecasts for AI agents. $0.01 per call.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables access to Hong Kong government's official open data portal (DATA.GOV.HK) through natural language queries. Supports searching datasets, browsing categories, and retrieving detailed information about Hong Kong's public data resources.822 PyPI9MIT
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to Taiwan's Central Weather Administration (CWA) Open Data API, offering 36 tools across 7 categories including weather forecasts, observations, earthquakes, and astronomy.MIT
- AlicenseBqualityCmaintenanceProvides access to Hong Kong climate and weather data from the Hong Kong Observatory, including current conditions, forecasts, warnings, tides, and more.1951 PyPI7MIT
- FlicenseNot gradedqualityDmaintenanceProvides tools to access Hong Kong Observatory open data, including weather forecasts, earthquake reports, climate datasets, lunar date conversion, and hourly rainfall.-