Hong Kong Bus Network MCP Interface

This Model Context Protocol (MCP) service grants Language Models dynamic querying capabilities over transit data pertaining to KMB (九龍巴士) and Long Win Bus (龍運巴士) networks in Hong Kong, focusing on real-time arrival data and itinerary structure. It empowers LMs to address inquiries regarding bus paths, stopping points, and estimated time of arrival (ETA).

Capabilities

• Provision of live bus arrival predictions (ETA)
• Extensive capability for route specification lookups
• Retrieval and searching of bus stopping locations
• Mapping between routes and their associated stops
• Integrated data caching mechanism to minimize external service calls
• Dual-language capability (English and Traditional Chinese)

Data Origin

This component leverages the public data conduit provided by KMB/LWB:

• Endpoint Root: https://data.etabus.gov.hk/v1/transport/kmb
• Official KMB Open Data API Reference

Prerequisites for Deployment

• Python Interpreter version 3.10 or newer is mandatory
• The 'uv' package management utility

Installation Procedures

Automated Setup via Smithery

To integrate this KMB Bus MCP service into Claude Desktop automatically utilizing Smithery:

npx -y @smithery/cli install @kennyckk/mcp_hkbus --client claude

Manual Deployment Steps

1. Install uv if it is not currently available:

curl -LsSf https://astral.sh/uv/install.sh | sh

1. Obtain the repository source code:

git clone git@github.com:kennyckk/mcp_hkbus.git
cd mcp_hkbus

1. Execute uv to resolve and install Python dependencies:

uv sync # Relies on uv.lock file

Operational Guide

1. Configure the MCP Client (e.g., Claude Desktop settings) by modifying the configuration file:

{
  "mcpServers": {
    "bus_service": {
      "command": "path/to/uv.exe",
      "args": ["--directory", "path/to/kmb_bus", "run", "kmb_mcp.py"],
      "background": true
    }
  }
}

1. The running service exposes the following callable functions for Language Model interaction:

2. get_route_list(): Retrieves the full catalog of active bus routes

3. get_stop_list(): Fetches a comprehensive directory of all designated bus stops
4. get_route_stops(): Queries the sequence of stops belonging to a specified route identifier
5. find_stops_by_name(): Executes a search across stop names using a provided keyword
6. get_all_routes_at_stop(): Identifies every transit line that services a particular bus stop ID
7. get_eta(): Calculates and returns the projected arrival time for a specified route/stop combination

Validation

Execute the integrated test suite using the pytest framework:

pytest test/kmb-mcp-tests.py

Essential Libraries

• httpx: Used for asynchronous network communications
• fastmcp: Core framework for hosting the MCP interface
• pytest: Utility for quality assurance testing (non-production)

Contributions

We welcome external contributions! Please submit suggestions or code via a Pull Request.

Credits

• Acknowledgment to KMB/LWB for API data accessibility
• Gratitude to the developers of the MCP specification

Important Notice

Operation of this service is contingent upon the KMB/LWB Open Data API. Users should implement robust error handling and remain conscious of potential service rate limitations in live deployments.