Skip to content
Back to search

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hongkong-ai-labs--hongkong-bus-skill/badge.svg)](/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

i

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
  1. ---
  2. name: hongkong-bus-skill
  3. 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.
  4. license: MIT
  5. ---
  6. # Hong Kong buses
  7. `hkbus` combines the five Hong Kong bus open-data feeds behind one command
  8. and one MCP server. It needs no API key and no account. It is an independent,
  9. unofficial project.
  10. Use it when the user asks about:
  11. - the next KMB, Citybus, green minibus, NLB or MTR Bus at a stop
  12. - which stops a route serves and in what order
  13. - which route goes from A to B in Hong Kong (KMB, Citybus and NLB; green
  14. minibus route discovery is not covered yet)
  15. - a Discovery Bay or Park Island coach
  16. - which red minibus goes from Kennedy Town to Shau Kei Wan, or what it costs
  17. ## Before first use
  18. ```console
  19. $ bash scripts/ensure-binary.sh
  20. /Users/you/.local/bin/hkbus
  21. ```
  22. ```bash
  23. BIN="$(bash scripts/ensure-binary.sh)"
  24. ```
  25. The script checks `$HKBUS_BIN`, `hkbus` on `PATH`, then builds with
  26. `cargo build --release --locked`. `scripts/install.sh` installs into
  27. `~/.local/bin`.
  28. ### Install the binary directly
  29. `npx skills add` installs the skill files. If the binary is missing, install it
  30. with the release installer or cargo:
  31. ```bash
  32. 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
  33. # or
  34. cargo install --git https://github.com/hongkong-ai-labs/hongkong-bus-skill --locked
  35. ```
  36. Register it with any MCP client:
  37. ```bash
  38. npx add-mcp "$(command -v hkbus) mcp" --name hongkong-bus -a claude-code -a codex -a cursor -y
  39. claude mcp add hongkong-bus -- hkbus mcp
  40. codex mcp add hongkong-bus -- hkbus mcp
  41. ```
  42. `add-mcp` detects the client configuration files in the current project; add
  43. `-g` for a global install. `$(command -v hkbus)` keeps the entry correct
  44. when the binary is on `PATH`; substitute an absolute path if your client does
  45. not inherit the shell `PATH`.
  46. ## CLI
  47. ```bash
  48. $BIN routes kmb --query 1
  49. $BIN routes ctb --query "Happy Valley"
  50. $BIN routes gmb --region HKI --query 1
  51. $BIN routes nlb --query "Tai O"
  52. $BIN routes mtrbus --query K51
  53. $BIN stops kmb 1 --direction outbound
  54. $BIN stops ctb 1
  55. $BIN stops gmb 1
  56. $BIN stops nlb 1
  57. $BIN stops mtrbus K51
  58. $BIN eta kmb 1 "Chuk Yuen"
  59. $BIN eta kmb 1 "Chuk Yuen" --direction outbound --json
  60. $BIN eta ctb 1 "Central"
  61. $BIN eta gmb N40 "Stanley Beach"
  62. $BIN eta nlb 1 "Mui Wo"
  63. $BIN eta mtrbus K51 K51-U210
  64. $BIN near 22.3193 114.1694 --radius 0.5 --limit 10
  65. $BIN near 22.2883 114.1504 --operator ctb --route 1 --radius 0.3
  66. $BIN journey "Chuk Yuen" "Central" --limit 3
  67. $BIN private
  68. $BIN private --query "Discovery Bay"
  69. $BIN private-eta NR330
  70. $BIN private-eta NR330 --direction 1 --json
  71. $BIN red-minibus --query "Kennedy Town"
  72. $BIN red-minibus --district "Sha Tin"
  73. $BIN red-route r_h08
  74. $BIN update --check
  75. ```
  76. Operators are `kmb` (KMB and LWB), `ctb` (Citybus), `gmb` (green minibus),
  77. `nlb` (New Lantao Bus) and `mtrbus` (MTR Bus). `--json` works globally.
  78. ### Routes
  79. `routes` searches the operator's published route list by route number, origin
  80. or destination. Use `--limit` to cap the output. Green minibus route lists are
  81. split by region: `HKI`, `KLN` or `NT`; without `--region` all three are
  82. searched.
  83. KMB publishes a direction (`O`/`I`) and a service type for each variant. Most
  84. routes have service type `1`; some have short-working or overnight variants
  85. with another type. The `stops` and `eta` commands use every matching variant
  86. unless `--direction` narrows it.
  87. ### Stops and ETAs
  88. `stops` prints stop sequence, stop id, name and direction. Use the id for an
  89. exact `eta` lookup, or a distinctive part of the name. The first matching stop
  90. is used, so a name that appears several times on a route should be narrowed
  91. with `--direction` or replaced by its id.
  92. `eta` returns minutes until arrival and the operator's remark (`Scheduled`,
  93. `Final Bus`, `Arriving / Departed`, and so on). An empty result is common late
  94. at night or at the end of a route; it does not mean the route does not exist.
  95. The renderer shows `no ETA` when the operator has a stop but no prediction.
  96. MTR Bus publishes stop ids but not stop names. `stops mtrbus` therefore shows
  97. the id in both columns, and `eta mtrbus` matches on the id.
  98. ### Nearby stops and journeys
  99. `near` finds stops around a WGS84 coordinate and prints the distance. KMB
  100. needs no route because it publishes a bulk stop list with coordinates;
  101. Citybus and NLB publish coordinates inside a route stop list, so pass
  102. `--route` for those. GMB and MTR Bus publish no stop coordinates, and `near`
  103. says so instead of returning an empty result.
  104. `journey` plans a **direct** route first and falls back to **one transfer**
  105. when there is no direct option. It searches the published KMB route-stop
  106. graph and asks Citybus and NLB only when KMB has no answer, because their stop
  107. details are one request per stop. Green minibus route discovery is not covered
  108. yet: GMB has no bulk route-stop endpoint, and a place-name search would need
  109. hundreds of requests.
  110. Journeys are route options, not live journey times. The planner does not know
  111. about service hours, walking interchanges or frequency, and a "stops" count is
  112. the number of published stops between boarding and alighting. Check the live
  113. ETA before setting out.
  114. ### Private coaches and red minibuses
  115. `private` lists the external routes and published adult fares of the largest
  116. private estate operators:
  117. - **Discovery Bay (DBTSL)** — DB01A / DB01R Tung Chung, DB02A / DB02R airport,
  118. DB03P / DB03R Sunny Bay, and DB08R Central overnight. Resident and regular
  119. fares are shown where DBTSL publishes them.
  120. - **Park Island (PITCL)** — NR330 Tsing Yi, NR332 Kwai Fong, NR334 airport,
  121. NR338 Central overnight and NR338S Central via Hong Kong Station. NR331 /
  122. NR331S are Sun Bus routes to Tsuen Wan; NR330A is the peak-hour Tsing Yi
  123. supplement.
  124. Park Island publishes live arrivals through its public ETA backend.
  125. `private-eta NR330` (also NR332, NR334, NR338) returns minutes to each stop for
  126. directions 1 and 2. Discovery Bay publishes timetables but not a public ETA
  127. feed, so this skill deliberately does not invent departure times there. Give
  128. the user the operator timetable for exact Discovery Bay times.
  129. Red minibuses are not scheduled, but they do have recognised route corridors.
  130. `red-minibus` lists routes scraped from the 16seats.net public directory, with
  131. district, service description and route code. Filters are `--query` (route or
  132. place) and `--district`. `red-route <code or name>` returns the published page:
  133. service period, fare table and major boarding/alighting points.
  134. Fares and routeing remain at the driver's discretion, and there is no live ETA.
  135. Quote the published fare as a range and tell the passenger to check the
  136. windscreen. Never invent a red minibus departure time.
  137. ## MCP
  138. ```bash
  139. $BIN mcp
  140. ```
  141. ```json
  142. {
  143. "mcpServers": {
  144. "hongkong-bus": {
  145. "command": "/absolute/path/to/hkbus",
  146. "args": ["mcp"]
  147. }
  148. }
  149. }
  150. ```
  151. Tools:
  152. | Tool | Arguments |
  153. | --- | --- |
  154. | `bus_routes` | `{ "operator": "kmb"\|"ctb"\|"gmb"\|"nlb"\|"mtrbus", "query"?: string, "region"?: "HKI"\|"KLN"\|"NT", "limit"?: number }` |
  155. | `bus_stops` | `{ "operator": string, "route": string, "direction"?: string }` |
  156. | `bus_eta` | `{ "operator": string, "route": string, "stop": string, "direction"?: string }` |
  157. | `private_bus_routes` | `{ "query"?: string }` |
  158. | `private_bus_eta` | `{ "route": "NR330"\|"NR332"\|"NR334"\|"NR338", "direction"?: 1\|2 }` |
  159. | `red_minibus_routes` | `{ "query"?: string, "district"?: string }` |
  160. | `red_minibus_route` | `{ "route": string }` |
  161. | `red_minibus_info` | `{}` |
  162. | `bus_stops_near` | `{ "lat": number, "lng": number, "operator"?: string, "route"?: string, "radius_km"?: number, "limit"?: number }` |
  163. | `bus_journey` | `{ "from": string, "to": string, "limit"?: number }` |
  164. The server speaks JSON-RPC 2.0 over stdio, one message per line, and implements
  165. `initialize`, `ping`, `tools/list` and `tools/call`.
  166. ## Cautions
  167. - ETA feeds are predictions. Traffic, weather and special arrangements can
  168. change them without notice.
  169. - A route number is not unique across operators. Say which operator you used
  170. when reporting a result.
  171. - KMB and Citybus stops are often paired by direction; check the direction and
  172. the destination before telling someone a bus is coming.
  173. - Fares are not exposed consistently across the live feeds. NLB publishes a
  174. fare per stop; the others do not. Private-coach and red-minibus fares come
  175. from published reference pages and can change at the operator's discretion.
  176. - This is not an official KMB, Citybus, GMB, NLB, MTR, PITCL or Transport
  177. Department channel.
  178. ## Sources
  179. - KMB/LWB: `https://data.etabus.gov.hk/v1/transport/kmb/`
  180. - Citybus: `https://rt.data.gov.hk/v2/transport/citybus/`
  181. - Green minibus: `https://data.etagmb.gov.hk/`
  182. - Red minibus directory: `https://www.16seats.net/eng/`
  183. - Discovery Bay: `https://www.visitdiscoverybay.com/en/getting-around`
  184. - Park Island live ETA: `https://360-api.socif.co/api/eta/route-stop/{route}/{direction}`
  185. - Park Island: `http://www.pitcl.com.hk/en/bus_service.php`
  186. - NLB: `https://rt.data.gov.hk/v2/transport/nlb/`
  187. - MTR Bus: `POST https://rt.data.gov.hk/v1/transport/mtr/bus/getSchedule`
  188. - Red minibus operating rules: `https://www.td.gov.hk/en/transport_in_hong_kong/public_transport/minibuses/index.html`
  189. Responses are cached in-process for 30 seconds (ETA), one hour (route and stop
  190. lists), six hours (red minibus pages) or one day (stop names).
README.md · README · 222 lines · 1 finding marked
  1. # hongkong-bus-skill
  2. Hong Kong bus routes, stops and live next-arrival times in one Rust CLI and
  3. MCP server.
  4. | Operator | Routes | Stops | Live ETA |
  5. | --- | --- | --- | --- |
  6. | KMB / LWB | yes | yes | yes |
  7. | Citybus | yes | yes | yes |
  8. | Green minibus (GMB) | yes | yes | yes |
  9. | New Lantao Bus (NLB) | yes | yes | yes |
  10. | MTR Bus | yes | ids only | yes |
  11. | Discovery Bay (DBTSL) | reference | no | no |
  12. | Park Island (PITCL) | reference | no | NR330/332/334/338 |
  13. | Red minibus (16seats.net) | yes | major points | no |
  14. ## Install
  15. **Agent skill** — installs `SKILL.md` and the binary bootstrap script:
  16. ```bash
  17. npx skills add hongkong-ai-labs/hongkong-bus-skill
  18. npx skills update # refresh the installed skill later
  19. ```
  20. **Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or
  21. aarch64, static musl), checksum-verified, into `~/.local/bin`:
  22. ```bash
  23. 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
  24. ```
  25. **From source** — Rust 1.89 or newer:
  26. ```bash
  27. git clone https://github.com/hongkong-ai-labs/hongkong-bus-skill
  28. cd hongkong-bus-skill
  29. cargo install --path . --locked
  30. # or directly from GitHub:
  31. cargo install --git https://github.com/hongkong-ai-labs/hongkong-bus-skill --locked
  32. # or: cargo build --release --locked # target/release/hkbus
  33. ```
  34. Verify:
  35. ```console
  36. $ hkbus --version
  37. ```
  38. ## Usage
  39. ```bash
  40. hkbus routes kmb --query 1
  41. hkbus routes gmb --region HKI --query 1
  42. hkbus stops kmb 1 --direction outbound
  43. hkbus eta kmb 1 "Chuk Yuen"
  44. hkbus eta ctb 1 "Central"
  45. hkbus eta gmb N40 "Stanley Beach"
  46. hkbus eta nlb 1 "Mui Wo"
  47. hkbus eta mtrbus K51 K51-U210
  48. hkbus near 22.3193 114.1694 --radius 0.5 --limit 10
  49. hkbus near 22.2883 114.1504 --operator ctb --route 1 --radius 0.3
  50. hkbus journey "Chuk Yuen" "Central" --limit 3
  51. hkbus private --query "Discovery Bay"
  52. hkbus private-eta NR330
  53. hkbus red-minibus --query "Kennedy Town"
  54. hkbus red-minibus --district "Sha Tin"
  55. hkbus red-route r_h08
  56. hkbus update --check
  57. ```
  58. `--json` before the subcommand prints structured output.
  59. ## Notes
  60. - KMB routes carry a direction and service type. `stops` and `eta` cover every
  61. matching variant unless `--direction` narrows them.
  62. - Green minibus route numbers are regional; `--region HKI|KLN|NT` avoids
  63. ambiguity.
  64. - An empty ETA list is normal at night or at a route's terminus. The CLI says
  65. `no ETA` when a stop exists but has no prediction.
  66. - `near` uses the KMB bulk stop list, which carries coordinates. Citybus and
  67. NLB need `--route` because their coordinates only appear in route stop
  68. lists. GMB and MTR Bus publish no stop coordinates.
  69. - `journey` returns direct routes first and a one-transfer option only when
  70. there is no direct route. It covers KMB, Citybus and NLB; GMB route
  71. discovery is not implemented because the feed has no bulk route-stop endpoint.
  72. A journey is a route option, not a live journey time.
  73. - MTR Bus publishes stop ids only. The feed does not include stop names.
  74. - Discovery Bay and Park Island routes and fares are reference data. Park
  75. Island NR330/332/334/338 have live ETA via `private-eta`; Discovery Bay has
  76. no public live arrival feed.
  77. - Red minibuses are not scheduled, but `red-minibus` lists recognised routes
  78. from the 16seats.net directory and `red-route` shows the published fares and
  79. major boarding points. There is still no live ETA.
  80. ## MCP
  81. ```json
  82. {
  83. "mcpServers": {
  84. "hongkong-bus": {
  85. "command": "/absolute/path/to/hkbus",
  86. "args": ["mcp"]
  87. }
  88. }
  89. }
  90. ```
  91. Register it with any MCP client:
  92. ```bash
  93. npx add-mcp "$(command -v hkbus) mcp" --name hongkong-bus -a claude-code -a codex -a cursor -y
  94. claude mcp add hongkong-bus -- hkbus mcp
  95. codex mcp add hongkong-bus -- hkbus mcp
  96. ```
  97. `add-mcp` detects the client configuration files in the current project; add
  98. `-g` for a global install. `$(command -v hkbus)` keeps the entry correct
  99. when the binary is on `PATH`; substitute an absolute path if your client does
  100. not inherit the shell `PATH`.
  101. Tools: `bus_routes`, `bus_stops`, `bus_eta`, `private_bus_routes`,
  102. `private_bus_eta`, `red_minibus_routes`, `red_minibus_route`,
  103. `red_minibus_info`, `bus_stops_near`, `bus_journey`. See
  104. [`SKILL.md`](SKILL.md) for schemas.
  105. ## Run modes and deployment
  106. | Mode | Start with | Use for |
  107. | --- | --- | --- |
  108. | CLI | `hkbus <command>` | Interactive use and shell scripts |
  109. | JSON | `<command>` with `--json` | `jq`, automation, other programs |
  110. | MCP stdio | `hkbus mcp` | Desktop and CLI MCP clients |
  111. | Container | `docker run --rm -i hkbus mcp` | No local Rust toolchain |
  112. ### MCP and authentication
  113. This server is **stdio-only**: the client launches the process and speaks MCP
  114. over stdin/stdout. There is no listening port, so there is no network
  115. authentication layer and no API-key setting. Optional API keys in this project
  116. family apply only to servers that expose an HTTP transport. Keep the process
  117. local and let the MCP client manage it.
  118. Typical client entry:
  119. ```json
  120. {
  121. "mcpServers": {
  122. "hongkong-bus-skill": {
  123. "command": "hkbus",
  124. "args": ["mcp"]
  125. }
  126. }
  127. }
  128. ```
  129. If the client does not inherit `PATH`, use the absolute installed path.
  130. ### Docker and Apple container
  131. ```bash
  132. docker build -t hkbus .
  133. docker run --rm hkbus --help
  134. docker run --rm -i hkbus mcp # stdio MCP
  135. docker compose run --rm stdio # same, through Compose
  136. ```
  137. Apple's `container` runtime uses the same OCI image:
  138. ```bash
  139. container build -t hkbus .
  140. container run --rm hkbus --help
  141. container run --rm -i hkbus mcp
  142. ```
  143. The runtime image contains the release binary and CA certificates, runs as a
  144. non-root user, and defaults to `--help` so a bare `docker run` is harmless.
  145. ### Cloudflare and WASM
  146. There is no Worker or WASM deployment. The binary talks directly to upstream
  147. HTTP APIs over TLS and uses a Tokio runtime; packaging it as a stdio server is
  148. the supported integration. A Worker would need a separate HTTP/JavaScript
  149. adapter and is out of scope for this repo.
  150. ### Releases
  151. Pushing a `v*` tag runs the release workflow, which checks the tag against
  152. `Cargo.toml` and `CHANGELOG.md`, builds four targets, smoke-tests native
  153. binaries and publishes:
  154. - `hkbus-<tag>-<target>.tar.gz` for macOS and static Linux
  155. - `SHA256SUMS` covering every tarball
  156. `scripts/install.sh` downloads the latest release, verifies its checksum and
  157. falls back to `cargo build --release --locked` when no release is available.
  158. `just tag X.Y.Z` creates the annotated tag locally; `just release X.Y.Z` tags
  159. and pushes to trigger the workflow.
  160. ## Development
  161. ```bash
  162. just # fmt check, clippy with -D warnings, tests
  163. just skill-check # validate SKILL.md and shell syntax
  164. just container # build the image and print CLI help
  165. cargo test
  166. cargo clippy -- -D warnings
  167. cargo fmt --check
  168. ```
  169. `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
  170. `clippy`, so `rustup` sets contributors up automatically. `just doc`
  171. builds the API documentation. See `CONTRIBUTING.md` for the full check
  172. list and the signed-commit requirement.
  173. ## Licence
  174. MIT. Independent project, not affiliated with any operator or the Transport
  175. Department.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.