Address MCP Server

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

Related MCP server: Australian Postcodes MCP Server

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:

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:

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:

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

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