Skip to main content
Glama

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

  1. Install dependencies:

npm install
  1. Start the MCP development server:

npm run inspect
  1. Build the MCP server:

npm run build
  1. Run tests:

npm test
  1. Run tests in watch mode:

npm run test:watch

Comprehensive 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 code

  • src/lib/ - API implementation modules

  • documentation/ - API documentation and test cases

  • scripts/ - Development utilities

  • src/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]
    end

REQ02xx: Earthquake Information

flowchart TD
    subgraph REQ02xx[Earthquake Information]
        C1[Quick Earthquake]
        C2[Felt Earthquake]
    end

REQ03xx: 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]
    end

REQ04xx: Lunar Calendar

flowchart TD
    subgraph REQ04xx[Lunar Calendar]
        E1[Lunar Date]
    end

REQ05xx: Rainfall

flowchart TD
    subgraph REQ05xx[Rainfall]
        F1[Hourly Rainfall]
    end

Credits:

Available Tools

20 tools
clmmaxtA

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

    B3.2/5.0

    Scored across 20 tools

    Disambiguation5/5

    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).

    Naming Consistency2/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      8
      22 PyPI
      9
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides tools to access Hong Kong Observatory open data, including weather forecasts, earthquake reports, climate datasets, lunar date conversion, and hourly rainfall.
      -