hongkong-bus-skill
Hong Kong bus routes, stop lists and live next-arrival ETAs from one Rust CLI and MCP server — KMB/LWB, Citybus, green minibus (GMB), New Lantao Bus (NLB) and MTR Bus, live Park Island coach arrivals, published routes and fares for private estate coaches such as Discovery Bay, and 16seats.net's red minibus route directory. Use for any question about Hong Kong buses, minibuses, stops or when the next bus arrives.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/hongkong-ai-labs--hongkong-bus-skill)HTML
<a href="/listings/hongkong-ai-labs--hongkong-bus-skill"><img src="/api/listings/hongkong-ai-labs--hongkong-bus-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
**Agent skill** — installs `SKILL.md` and the binary bootstrap script:
npx skills add hongkong-ai-labs/hongkong-bus-skill npx skills update # refresh the installed skill later
**Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or aarch64, static musl), checksum-verified, into `~/.local/bin`:
curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-bus-skill/main/scripts/install.sh | sh
**From source** — Rust 1.89 or newer:
git clone https://github.com/hongkong-ai-labs/hongkong-bus-skill cd hongkong-bus-skill cargo install --path . --locked # or directly from GitHub: cargo install --git https://github.com/hongkong-ai-labs/hongkong-bus-skill --locked # or: cargo build --release --locked # target/release/hkbus
Verify:
$ hkbus --version
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 239 lines · 1 finding marked
- ---
- name: hongkong-bus-skill
- description: Hong Kong bus routes, stop lists and live next-arrival ETAs from one Rust CLI and MCP server — KMB/LWB, Citybus, green minibus (GMB), New Lantao Bus (NLB) and MTR Bus, live Park Island coach arrivals, published routes and fares for private estate coaches such as Discovery Bay, and 16seats.net's red minibus route directory. Use for any question about Hong Kong buses, minibuses, stops or when the next bus arrives.
- license: MIT
- ---
- # Hong Kong buses
- `hkbus` combines the five Hong Kong bus open-data feeds behind one command
- and one MCP server. It needs no API key and no account. It is an independent,
- unofficial project.
- Use it when the user asks about:
- - the next KMB, Citybus, green minibus, NLB or MTR Bus at a stop
- - which stops a route serves and in what order
- - which route goes from A to B in Hong Kong (KMB, Citybus and NLB; green
- minibus route discovery is not covered yet)
- - a Discovery Bay or Park Island coach
- - which red minibus goes from Kennedy Town to Shau Kei Wan, or what it costs
- ## Before first use
- ```console
- $ bash scripts/ensure-binary.sh
- /Users/you/.local/bin/hkbus
- ```
- ```bash
- BIN="$(bash scripts/ensure-binary.sh)"
- ```
- The script checks `$HKBUS_BIN`, `hkbus` on `PATH`, then builds with
- `cargo build --release --locked`. `scripts/install.sh` installs into
- `~/.local/bin`.
- ### Install the binary directly
- `npx skills add` installs the skill files. If the binary is missing, install it
- with the release installer or cargo:
- ```bash
- curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-bus-skill/main/scripts/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 43 on GitHub
- # or
- cargo install --git https://github.com/hongkong-ai-labs/hongkong-bus-skill --locked
- ```
- Register it with any MCP client:
- ```bash
- npx add-mcp "$(command -v hkbus) mcp" --name hongkong-bus -a claude-code -a codex -a cursor -y
- claude mcp add hongkong-bus -- hkbus mcp
- codex mcp add hongkong-bus -- hkbus mcp
- ```
- `add-mcp` detects the client configuration files in the current project; add
- `-g` for a global install. `$(command -v hkbus)` keeps the entry correct
- when the binary is on `PATH`; substitute an absolute path if your client does
- not inherit the shell `PATH`.
- ## CLI
- ```bash
- $BIN routes kmb --query 1
- $BIN routes ctb --query "Happy Valley"
- $BIN routes gmb --region HKI --query 1
- $BIN routes nlb --query "Tai O"
- $BIN routes mtrbus --query K51
- $BIN stops kmb 1 --direction outbound
- $BIN stops ctb 1
- $BIN stops gmb 1
- $BIN stops nlb 1
- $BIN stops mtrbus K51
- $BIN eta kmb 1 "Chuk Yuen"
- $BIN eta kmb 1 "Chuk Yuen" --direction outbound --json
- $BIN eta ctb 1 "Central"
- $BIN eta gmb N40 "Stanley Beach"
- $BIN eta nlb 1 "Mui Wo"
- $BIN eta mtrbus K51 K51-U210
- $BIN near 22.3193 114.1694 --radius 0.5 --limit 10
- $BIN near 22.2883 114.1504 --operator ctb --route 1 --radius 0.3
- $BIN journey "Chuk Yuen" "Central" --limit 3
- $BIN private
- $BIN private --query "Discovery Bay"
- $BIN private-eta NR330
- $BIN private-eta NR330 --direction 1 --json
- $BIN red-minibus --query "Kennedy Town"
- $BIN red-minibus --district "Sha Tin"
- $BIN red-route r_h08
- $BIN update --check
- ```
- Operators are `kmb` (KMB and LWB), `ctb` (Citybus), `gmb` (green minibus),
- `nlb` (New Lantao Bus) and `mtrbus` (MTR Bus). `--json` works globally.
- ### Routes
- `routes` searches the operator's published route list by route number, origin
- or destination. Use `--limit` to cap the output. Green minibus route lists are
- split by region: `HKI`, `KLN` or `NT`; without `--region` all three are
- searched.
- KMB publishes a direction (`O`/`I`) and a service type for each variant. Most
- routes have service type `1`; some have short-working or overnight variants
- with another type. The `stops` and `eta` commands use every matching variant
- unless `--direction` narrows it.
- ### Stops and ETAs
- `stops` prints stop sequence, stop id, name and direction. Use the id for an
- exact `eta` lookup, or a distinctive part of the name. The first matching stop
- is used, so a name that appears several times on a route should be narrowed
- with `--direction` or replaced by its id.
- `eta` returns minutes until arrival and the operator's remark (`Scheduled`,
- `Final Bus`, `Arriving / Departed`, and so on). An empty result is common late
- at night or at the end of a route; it does not mean the route does not exist.
- The renderer shows `no ETA` when the operator has a stop but no prediction.
- MTR Bus publishes stop ids but not stop names. `stops mtrbus` therefore shows
- the id in both columns, and `eta mtrbus` matches on the id.
- ### Nearby stops and journeys
- `near` finds stops around a WGS84 coordinate and prints the distance. KMB
- needs no route because it publishes a bulk stop list with coordinates;
- Citybus and NLB publish coordinates inside a route stop list, so pass
- `--route` for those. GMB and MTR Bus publish no stop coordinates, and `near`
- says so instead of returning an empty result.
- `journey` plans a **direct** route first and falls back to **one transfer**
- when there is no direct option. It searches the published KMB route-stop
- graph and asks Citybus and NLB only when KMB has no answer, because their stop
- details are one request per stop. Green minibus route discovery is not covered
- yet: GMB has no bulk route-stop endpoint, and a place-name search would need
- hundreds of requests.
- Journeys are route options, not live journey times. The planner does not know
- about service hours, walking interchanges or frequency, and a "stops" count is
- the number of published stops between boarding and alighting. Check the live
- ETA before setting out.
- ### Private coaches and red minibuses
- `private` lists the external routes and published adult fares of the largest
- private estate operators:
- - **Discovery Bay (DBTSL)** — DB01A / DB01R Tung Chung, DB02A / DB02R airport,
- DB03P / DB03R Sunny Bay, and DB08R Central overnight. Resident and regular
- fares are shown where DBTSL publishes them.
- - **Park Island (PITCL)** — NR330 Tsing Yi, NR332 Kwai Fong, NR334 airport,
- NR338 Central overnight and NR338S Central via Hong Kong Station. NR331 /
- NR331S are Sun Bus routes to Tsuen Wan; NR330A is the peak-hour Tsing Yi
- supplement.
- Park Island publishes live arrivals through its public ETA backend.
- `private-eta NR330` (also NR332, NR334, NR338) returns minutes to each stop for
- directions 1 and 2. Discovery Bay publishes timetables but not a public ETA
- feed, so this skill deliberately does not invent departure times there. Give
- the user the operator timetable for exact Discovery Bay times.
- Red minibuses are not scheduled, but they do have recognised route corridors.
- `red-minibus` lists routes scraped from the 16seats.net public directory, with
- district, service description and route code. Filters are `--query` (route or
- place) and `--district`. `red-route <code or name>` returns the published page:
- service period, fare table and major boarding/alighting points.
- Fares and routeing remain at the driver's discretion, and there is no live ETA.
- Quote the published fare as a range and tell the passenger to check the
- windscreen. Never invent a red minibus departure time.
- ## MCP
- ```bash
- $BIN mcp
- ```
- ```json
- {
- "mcpServers": {
- "hongkong-bus": {
- "command": "/absolute/path/to/hkbus",
- "args": ["mcp"]
- }
- }
- }
- ```
- Tools:
- | Tool | Arguments |
- | --- | --- |
- | `bus_routes` | `{ "operator": "kmb"\|"ctb"\|"gmb"\|"nlb"\|"mtrbus", "query"?: string, "region"?: "HKI"\|"KLN"\|"NT", "limit"?: number }` |
- | `bus_stops` | `{ "operator": string, "route": string, "direction"?: string }` |
- | `bus_eta` | `{ "operator": string, "route": string, "stop": string, "direction"?: string }` |
- | `private_bus_routes` | `{ "query"?: string }` |
- | `private_bus_eta` | `{ "route": "NR330"\|"NR332"\|"NR334"\|"NR338", "direction"?: 1\|2 }` |
- | `red_minibus_routes` | `{ "query"?: string, "district"?: string }` |
- | `red_minibus_route` | `{ "route": string }` |
- | `red_minibus_info` | `{}` |
- | `bus_stops_near` | `{ "lat": number, "lng": number, "operator"?: string, "route"?: string, "radius_km"?: number, "limit"?: number }` |
- | `bus_journey` | `{ "from": string, "to": string, "limit"?: number }` |
- The server speaks JSON-RPC 2.0 over stdio, one message per line, and implements
- `initialize`, `ping`, `tools/list` and `tools/call`.
- ## Cautions
- - ETA feeds are predictions. Traffic, weather and special arrangements can
- change them without notice.
- - A route number is not unique across operators. Say which operator you used
- when reporting a result.
- - KMB and Citybus stops are often paired by direction; check the direction and
- the destination before telling someone a bus is coming.
- - Fares are not exposed consistently across the live feeds. NLB publishes a
- fare per stop; the others do not. Private-coach and red-minibus fares come
- from published reference pages and can change at the operator's discretion.
- - This is not an official KMB, Citybus, GMB, NLB, MTR, PITCL or Transport
- Department channel.
- ## Sources
- - KMB/LWB: `https://data.etabus.gov.hk/v1/transport/kmb/`
- - Citybus: `https://rt.data.gov.hk/v2/transport/citybus/`
- - Green minibus: `https://data.etagmb.gov.hk/`
- - Red minibus directory: `https://www.16seats.net/eng/`
- - Discovery Bay: `https://www.visitdiscoverybay.com/en/getting-around`
- - Park Island live ETA: `https://360-api.socif.co/api/eta/route-stop/{route}/{direction}`
- - Park Island: `http://www.pitcl.com.hk/en/bus_service.php`
- - NLB: `https://rt.data.gov.hk/v2/transport/nlb/`
- - MTR Bus: `POST https://rt.data.gov.hk/v1/transport/mtr/bus/getSchedule`
- - Red minibus operating rules: `https://www.td.gov.hk/en/transport_in_hong_kong/public_transport/minibuses/index.html`
- Responses are cached in-process for 30 seconds (ETA), one hour (route and stop
- lists), six hours (red minibus pages) or one day (stop names).
README.md · README · 222 lines · 1 finding marked
- # hongkong-bus-skill
- Hong Kong bus routes, stops and live next-arrival times in one Rust CLI and
- MCP server.
- | Operator | Routes | Stops | Live ETA |
- | --- | --- | --- | --- |
- | KMB / LWB | yes | yes | yes |
- | Citybus | yes | yes | yes |
- | Green minibus (GMB) | yes | yes | yes |
- | New Lantao Bus (NLB) | yes | yes | yes |
- | MTR Bus | yes | ids only | yes |
- | Discovery Bay (DBTSL) | reference | no | no |
- | Park Island (PITCL) | reference | no | NR330/332/334/338 |
- | Red minibus (16seats.net) | yes | major points | no |
- ## Install
- **Agent skill** — installs `SKILL.md` and the binary bootstrap script:
- ```bash
- npx skills add hongkong-ai-labs/hongkong-bus-skill
- npx skills update # refresh the installed skill later
- ```
- **Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or
- aarch64, static musl), checksum-verified, into `~/.local/bin`:
- ```bash
- curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-bus-skill/main/scripts/install.sh | sh
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 30 on GitHub
- ```
- **From source** — Rust 1.89 or newer:
- ```bash
- git clone https://github.com/hongkong-ai-labs/hongkong-bus-skill
- cd hongkong-bus-skill
- cargo install --path . --locked
- # or directly from GitHub:
- cargo install --git https://github.com/hongkong-ai-labs/hongkong-bus-skill --locked
- # or: cargo build --release --locked # target/release/hkbus
- ```
- Verify:
- ```console
- $ hkbus --version
- ```
- ## Usage
- ```bash
- hkbus routes kmb --query 1
- hkbus routes gmb --region HKI --query 1
- hkbus stops kmb 1 --direction outbound
- hkbus eta kmb 1 "Chuk Yuen"
- hkbus eta ctb 1 "Central"
- hkbus eta gmb N40 "Stanley Beach"
- hkbus eta nlb 1 "Mui Wo"
- hkbus eta mtrbus K51 K51-U210
- hkbus near 22.3193 114.1694 --radius 0.5 --limit 10
- hkbus near 22.2883 114.1504 --operator ctb --route 1 --radius 0.3
- hkbus journey "Chuk Yuen" "Central" --limit 3
- hkbus private --query "Discovery Bay"
- hkbus private-eta NR330
- hkbus red-minibus --query "Kennedy Town"
- hkbus red-minibus --district "Sha Tin"
- hkbus red-route r_h08
- hkbus update --check
- ```
- `--json` before the subcommand prints structured output.
- ## Notes
- - KMB routes carry a direction and service type. `stops` and `eta` cover every
- matching variant unless `--direction` narrows them.
- - Green minibus route numbers are regional; `--region HKI|KLN|NT` avoids
- ambiguity.
- - An empty ETA list is normal at night or at a route's terminus. The CLI says
- `no ETA` when a stop exists but has no prediction.
- - `near` uses the KMB bulk stop list, which carries coordinates. Citybus and
- NLB need `--route` because their coordinates only appear in route stop
- lists. GMB and MTR Bus publish no stop coordinates.
- - `journey` returns direct routes first and a one-transfer option only when
- there is no direct route. It covers KMB, Citybus and NLB; GMB route
- discovery is not implemented because the feed has no bulk route-stop endpoint.
- A journey is a route option, not a live journey time.
- - MTR Bus publishes stop ids only. The feed does not include stop names.
- - Discovery Bay and Park Island routes and fares are reference data. Park
- Island NR330/332/334/338 have live ETA via `private-eta`; Discovery Bay has
- no public live arrival feed.
- - Red minibuses are not scheduled, but `red-minibus` lists recognised routes
- from the 16seats.net directory and `red-route` shows the published fares and
- major boarding points. There is still no live ETA.
- ## MCP
- ```json
- {
- "mcpServers": {
- "hongkong-bus": {
- "command": "/absolute/path/to/hkbus",
- "args": ["mcp"]
- }
- }
- }
- ```
- Register it with any MCP client:
- ```bash
- npx add-mcp "$(command -v hkbus) mcp" --name hongkong-bus -a claude-code -a codex -a cursor -y
- claude mcp add hongkong-bus -- hkbus mcp
- codex mcp add hongkong-bus -- hkbus mcp
- ```
- `add-mcp` detects the client configuration files in the current project; add
- `-g` for a global install. `$(command -v hkbus)` keeps the entry correct
- when the binary is on `PATH`; substitute an absolute path if your client does
- not inherit the shell `PATH`.
- Tools: `bus_routes`, `bus_stops`, `bus_eta`, `private_bus_routes`,
- `private_bus_eta`, `red_minibus_routes`, `red_minibus_route`,
- `red_minibus_info`, `bus_stops_near`, `bus_journey`. See
- [`SKILL.md`](SKILL.md) for schemas.
- ## Run modes and deployment
- | Mode | Start with | Use for |
- | --- | --- | --- |
- | CLI | `hkbus <command>` | Interactive use and shell scripts |
- | JSON | `<command>` with `--json` | `jq`, automation, other programs |
- | MCP stdio | `hkbus mcp` | Desktop and CLI MCP clients |
- | Container | `docker run --rm -i hkbus mcp` | No local Rust toolchain |
- ### MCP and authentication
- This server is **stdio-only**: the client launches the process and speaks MCP
- over stdin/stdout. There is no listening port, so there is no network
- authentication layer and no API-key setting. Optional API keys in this project
- family apply only to servers that expose an HTTP transport. Keep the process
- local and let the MCP client manage it.
- Typical client entry:
- ```json
- {
- "mcpServers": {
- "hongkong-bus-skill": {
- "command": "hkbus",
- "args": ["mcp"]
- }
- }
- }
- ```
- If the client does not inherit `PATH`, use the absolute installed path.
- ### Docker and Apple container
- ```bash
- docker build -t hkbus .
- docker run --rm hkbus --help
- docker run --rm -i hkbus mcp # stdio MCP
- docker compose run --rm stdio # same, through Compose
- ```
- Apple's `container` runtime uses the same OCI image:
- ```bash
- container build -t hkbus .
- container run --rm hkbus --help
- container run --rm -i hkbus mcp
- ```
- The runtime image contains the release binary and CA certificates, runs as a
- non-root user, and defaults to `--help` so a bare `docker run` is harmless.
- ### Cloudflare and WASM
- There is no Worker or WASM deployment. The binary talks directly to upstream
- HTTP APIs over TLS and uses a Tokio runtime; packaging it as a stdio server is
- the supported integration. A Worker would need a separate HTTP/JavaScript
- adapter and is out of scope for this repo.
- ### Releases
- Pushing a `v*` tag runs the release workflow, which checks the tag against
- `Cargo.toml` and `CHANGELOG.md`, builds four targets, smoke-tests native
- binaries and publishes:
- - `hkbus-<tag>-<target>.tar.gz` for macOS and static Linux
- - `SHA256SUMS` covering every tarball
- `scripts/install.sh` downloads the latest release, verifies its checksum and
- falls back to `cargo build --release --locked` when no release is available.
- `just tag X.Y.Z` creates the annotated tag locally; `just release X.Y.Z` tags
- and pushes to trigger the workflow.
- ## Development
- ```bash
- just # fmt check, clippy with -D warnings, tests
- just skill-check # validate SKILL.md and shell syntax
- just container # build the image and print CLI help
- cargo test
- cargo clippy -- -D warnings
- cargo fmt --check
- ```
- `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
- `clippy`, so `rustup` sets contributors up automatically. `just doc`
- builds the API documentation. See `CONTRIBUTING.md` for the full check
- list and the signed-commit requirement.
- ## Licence
- MIT. Independent project, not affiliated with any operator or the Transport
- Department.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.