HongKongAddressMCP

A Model Context Protocol (MCP) server for Hong Kong address lookup and correction using the Address Lookup Service (ALS) open data from the HKSAR Government.

Features

• Fuzzy address matching — Corrects typos in building names, street names, estate names (Chinese & English)
• Structured input parsing — Parses the standard HK address form format (室/層/樓/大廈名稱/街名及街號/地區)
• Free-text search — Search by any combination of address fields
• Bilingual — Full support for Traditional Chinese and English addresses
• LLM-powered correction — Uses Dify LLM API to compose the final corrected full address
• Offline fallback — Falls back to local-only matching if LLM is unavailable
• GeoAddress & Coordinates — Returns GeoAddress identifiers and WGS84 coordinates

Data Source

Uses the ALS GeoJSON files (18 district files) from DATA.GOV.HK:

• als_addresses_(district_name).geojson — One file per District Council district

Tools

check_address

Look up and correct a Hong Kong address using structured fields.

Parameters:

Field	Description	Example
buildingName	Building name (大廈名稱)	其士商業中心
streetName	Street name (街名)	宏開道
buildingNo	Street number (街號)	8
estateName	Estate name (屋邨/屋苑)	德福花園
villageName	Village name (村)	三家村
district	District (地區)	九龍灣
region	Region (地區選項)	九龍 / KLN
floor	Floor (層)	8
unit	Unit/Room (室)	215

parse_and_check_address

Parse a structured Chinese address form and look up/correct it.

Input example:

室：215
層：8
樓：(未填寫)
大廈名稱：科士商業中心
屋邨／屋苑／村：(未填寫)
街名及街號：宏開道 8號
地區：九龍灣
地區選項：已勾選 九龍

Output: Identifies that "科士商業中心" should be "其士商業中心" (CHEVALIER COMMERCIAL CENTRE).

correct_address ⭐ (Recommended)

The main tool — parses, looks up, and corrects an address using ALS open data + Dify LLM. Returns the final corrected full address.

Parameters:

Field	Description
address	Any address text — structured form or free text (Chinese/English)

Example output:

CHINESE: 九龍觀塘區宏開道8號其士商業中心8樓215室
ENGLISH: Unit 215, 8/F, CHEVALIER COMMERCIAL CENTRE, 8 WANG HOI ROAD, KWUN TONG DISTRICT, KLN
GEOADDRESS: 3981120257T20050430
CORRECTIONS: 大廈名稱: "科士商業中心" → "其士商業中心" (CHEVALIER COMMERCIAL CENTRE)

search_address_by_text

Free-text search for addresses.

Parameters:

Field	Description
query	Free-text query (Chinese or English)
maxResults	Max results (default: 5)

Setup

Install dependencies

npm install

Configure Environment Variables

Copy the example environment file and update with your credentials:

cp .env.example .env

Edit .env to set your Dify API credentials:

DIFY_API_KEY=your-api-key-here
DIFY_API_ENDPOINT=https://your-dify-endpoint.com/v1

Note: The .env file is gitignored to protect your credentials.

Run as MCP server

node index.js

Configure in your MCP client

Add to your MCP settings (e.g. ~/.cursor/mcp.json or Windsurf MCP config):

{
  "mcpServers": {
    "address-mcp": {
      "command": "node",
      "args": ["/Users/hillmantam/AddressMCP/index.js"]
    }
  }
}

Environment Variables Reference

Variable	Required	Description
DIFY_API_KEY	Yes	Your Dify API key
DIFY_API_ENDPOINT	Yes	Your Dify API base URL (e.g., https://your-endpoint.com/v1)

Run tests

npm test

Example Correction

Input: 科士商業中心 at 宏開道 8號, 九龍灣

Output:

• ⚠️ 大廈名稱: "科士商業中心" → "其士商業中心" (CHEVALIER COMMERCIAL CENTRE)
• Correct address: 九龍觀塘區宏開道8號其士商業中心
• GeoAddress: 3981120257T20050430
• Coordinates: 22.32133, 114.21127

Architecture

User Input → Parse structured fields → Fuse.js fuzzy search (local GeoJSON)
                                          ↓
                                    Top 5 candidates
                                          ↓
                                    Dify LLM API → Final corrected address
                                          ↓
                              (Fallback: local-only if LLM fails)

• Fuse.js — Fuzzy string matching for Chinese and English text
• Dify LLM — AI-powered address correction and formatting
• MCP SDK — Standard Model Context Protocol server over stdio
• GeoJSON — All 18 district files loaded into memory with indexed search