KMB Bus

You run an MCP server that gives real-time access to Hong Kong’s KMB and Long Win Bus routes, stops, and estimated arrivals. By hosting this server, you can answer user questions about routes, stops, and ETAs quickly and accurately through your language model client.

How to use

You connect an MCP client to the KMB Bus MCP Server to access live bus data. Use the provided MCP server configuration to spin up the local bus service, then query capabilities such as listing routes, finding stops by name, retrieving stops on a route, and getting estimated arrival times.

How to install

Prerequisites you need before starting:

• Python 3.10 or higher

• uv package manager

Choose one of the following installation paths.

# Option A: Install via Smithery (automatic for Claude Desktop)
npx -y @smithery/cli install @kennyckk/mcp_hkbus --client claude

# Option B: Manual installation
# 1) Install uv if you haven’t already
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2) Clone the repository
git clone git@github.com:kennyckk/mcp_hkbus.git
cd mcp_hkbus
# 3) Use uv to handle the python package
uv sync #using uv.lock

Manual installation steps in detail

If you prefer to set up manually, follow these steps exactly as shown.

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the KMB bus MCP repository
git clone git@github.com:kennyckk/mcp_hkbus.git
cd mcp_hkbus

# Prepare the Python dependencies using uv
uv sync

Configure your MCP client

Create or edit your MCP client configuration to point to the bus service MCP. You will run the stdio MCP server using uv, so provide the command and arguments as shown below.

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

What you can query (tools and capabilities)

The server exposes a set of tools you can call from your MCP client to retrieve bus information.

Available tools include these endpoints:

Tools and endpoints

• get_route_list(): Retrieve a list of all bus routes

• get_stop_list(): Retrieve a list of all bus stops

• get_route_stops(): Retrieve stops for a specific route

• find_stops_by_name(): Search for bus stops by name

• get_all_routes_at_stop(): Retrieve all routes serving a specific stop

• get_eta(): Retrieve estimated arrival times

Notes on data and usage

Data is sourced from the KMB/LWB Open Data API. Expect real-time results and be mindful of API rate limits. The server supports bilingual responses (English and Traditional Chinese) and caches data to optimize API calls.

If you run into issues, check that uv is syncing dependencies correctly and that the Python runtime is available on the system you deploy to.

Testing and maintenance

Run the test suite to verify functionality during development.

pytest test/kmb-mcp-tests.py

Security and reliability

Respect API rate limits of the underlying data source and implement error handling for API failures. Run servers with proper monitoring and consider caching strategies to reduce redundant API calls.

Available tools

get_route_list

Returns a list of all bus routes available in the KMB/LWB network.

get_stop_list

Returns a complete list of bus stops served by KMB/LWB.

get_route_stops

Fetches the sequence of stops for a specified bus route.

find_stops_by_name

Searches and returns stops matching a given name or partial name.

get_all_routes_at_stop

Lists all routes that serve a specific stop.

get_eta

Provides estimated arrival times for buses at a given stop or route.