Skip to content
Back to search

hongkong-chinabus-skill

Hong Kong cross-border travel from one Rust CLI and MCP server — live Immigration Department queue times at every land boundary, GoByBus coach schedules and prices to mainland China and Macao, the Marine Department cross-boundary ferry board, East Rail service information, and the official MTR high-speed rail timetable for Shenzhen and Guangzhou. Use for any question about crossing between Hong Kong, Shenzhen, Macao, Zhuhai or the mainland.

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-chinabus-skill/badge.svg)](/listings/hongkong-ai-labs--hongkong-chinabus-skill)

HTML

<a href="/listings/hongkong-ai-labs--hongkong-chinabus-skill"><img src="/api/listings/hongkong-ai-labs--hongkong-chinabus-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-chinabus-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-chinabus-skill/main/scripts/install.sh | sh

**From source** — Rust 1.89 or newer:

git clone https://github.com/hongkong-ai-labs/hongkong-chinabus-skill
cd hongkong-chinabus-skill
cargo install --path . --locked
# or directly from GitHub:
cargo install --git https://github.com/hongkong-ai-labs/hongkong-chinabus-skill --locked
# or: cargo build --release --locked   # target/release/hkchinabus

Verify:

$ hkchinabus --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 · 216 lines · 1 finding marked
  1. ---
  2. name: hongkong-chinabus-skill
  3. description: Hong Kong cross-border travel from one Rust CLI and MCP server — live Immigration Department queue times at every land boundary, GoByBus coach schedules and prices to mainland China and Macao, the Marine Department cross-boundary ferry board, East Rail service information, and the official MTR high-speed rail timetable for Shenzhen and Guangzhou. Use for any question about crossing between Hong Kong, Shenzhen, Macao, Zhuhai or the mainland.
  4. license: MIT
  5. ---
  6. # Hong Kong cross-border travel
  7. `hkchinabus` answers "how do I get across the boundary, and how busy is it?"
  8. from official Hong Kong government feeds plus GoByBus, the main cross-border
  9. coach booking platform. It needs no API key and no account. It is an
  10. independent, unofficial project.
  11. Use it when the user asks about:
  12. - how long the queue is at Lo Wu, Lok Ma Chau, Shenzhen Bay, HZMB, Huanggang,
  13. Heung Yuen Wai, Man Kam To or Sha Tau Kok
  14. - a coach from Hong Kong to Shenzhen, Guangzhou, Macao, Zhuhai or another
  15. mainland city, with departure times and prices
  16. - which Hong Kong boarding points serve a particular mainland or Macao hotel
  17. - ferries between Hong Kong and Macao, Shekou, Zhuhai, Zhongshan or Nansha
  18. - the East Rail to Lo Wu or Lok Ma Chau
  19. - high-speed rail from West Kowloon to Futian, Shenzhen North or Guangzhou
  20. ## Before first use
  21. ```console
  22. $ bash scripts/ensure-binary.sh
  23. /Users/you/.local/bin/hkchinabus
  24. ```
  25. ```bash
  26. BIN="$(bash scripts/ensure-binary.sh)"
  27. ```
  28. The script checks `$HKCHINABUS_BIN`, `hkchinabus` on `PATH`, then builds with
  29. `cargo build --release --locked`. `scripts/install.sh` installs into
  30. `~/.local/bin`.
  31. ### Install the binary directly
  32. `npx skills add` installs the skill files. If the binary is missing, install it
  33. with the release installer or cargo:
  34. ```bash
  35. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-chinabus-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 46 on GitHub
  36. # or
  37. cargo install --git https://github.com/hongkong-ai-labs/hongkong-chinabus-skill --locked
  38. ```
  39. Register it with any MCP client:
  40. ```bash
  41. npx add-mcp "$(command -v hkchinabus) mcp" --name hongkong-chinabus -a claude-code -a codex -a cursor -y
  42. claude mcp add hongkong-chinabus -- hkchinabus mcp
  43. codex mcp add hongkong-chinabus -- hkchinabus mcp
  44. ```
  45. `add-mcp` detects the client configuration files in the current project; add
  46. `-g` for a global install. `$(command -v hkchinabus)` keeps the entry correct
  47. when the binary is on `PATH`; substitute an absolute path if your client does
  48. not inherit the shell `PATH`.
  49. ## CLI
  50. All times are Hong Kong time (UTC+8). Add `--json` anywhere for
  51. machine-readable output.
  52. ```bash
  53. $BIN borders
  54. $BIN borders --point SBC
  55. $BIN borders --point "Lo Wu" --json
  56. $BIN coaches --list # busiest boarding points
  57. $BIN coaches --from "China HK City" # where can I go from here?
  58. $BIN coaches --from "China HK City" --to "MGM Cotai" --date 2026-11-22
  59. $BIN coaches --from 14905 --to "Hong Kong Airport" --json
  60. $BIN ferries
  61. $BIN ferries --terminal cft --port Macao
  62. $BIN ferries --port Shekou --direction departure --json
  63. $BIN rail east-rail
  64. $BIN rail east-rail --station lmc
  65. $BIN rail hsr
  66. $BIN rail hsr --to "Shenzhen North" --limit 12
  67. $BIN rail hsr --to "Guangzhou South" --json
  68. $BIN update --check
  69. ```
  70. ### Border queues
  71. `borders` reads the Immigration Department mobile app feed, which refreshes
  72. roughly every 15 minutes. It reports resident and visitor queues separately
  73. for arrivals and departures. Bands are:
  74. | Published value | Meaning |
  75. | --- | --- |
  76. | 0 | normal, under about 15 minutes |
  77. | 1 | busy, about 15–30 minutes |
  78. | 2 | very busy, about 30–60 minutes |
  79. | 3 | very busy, over about 60 minutes |
  80. | 99 | closed or not in service |
  81. A point showing 99 outside its opening hours is normal, not an error. Do not
  82. describe 99 as "no queue".
  83. ### Coaches (GoByBus)
  84. `--from` accepts a station name or GoByBus id. Names resolve exactly first,
  85. then by substring; an ambiguous name returns the candidate ids instead of
  86. guessing. `--to` is resolved against the destinations actually served from
  87. that origin, so a valid hotel on the other side of the city is not offered if
  88. no coach runs there.
  89. `--date` defaults to today and must be within 60 days. GoByBus normally opens
  90. sales a few weeks ahead; an empty list can simply mean seats are not on sale
  91. yet, not that the route does not exist.
  92. The directory contains 780+ boarding and alighting points across Hong Kong,
  93. Shenzhen, Guangzhou, Macao, Zhuhai and other mainland cities. `--list` shows
  94. the boarding points with the widest choice of destinations. The station
  95. directory is cached for one hour.
  96. Fields in `--json` trips: `route_number`, `from`, `to`, `depart`, `arrive`,
  97. `price`, `currency`, `seats_available`, `coach_type` (`bus` or `car`),
  98. `option_id`. Seat counts and prices are live snapshots and can change between
  99. the query and checkout.
  100. ### Ferries
  101. `ferries` parses the Marine Department cross-boundary ferry berthing board for
  102. China Ferry Terminal (CFT) and Macau Ferry Terminal (MFT). Records are
  103. arrivals and departures, not a ticket inventory. Each movement has `time`,
  104. `direction`, `port`, `operator`, `terminal`, `berth` and `status`.
  105. Typical ports include Macao, Macao (Taipa), Shekou, Zhuhai, Zhongshan and Nan
  106. Sha. The board is cached for 90 seconds. Outside service hours the board can be
  107. empty or still show the previous day's final sailings; check the timestamp.
  108. ### Rail
  109. East Rail information here is reference data. It covers Lo Wu (`low`) and Lok
  110. Ma Chau (`lmc`), the interchange at Sheung Shui, approximate first and last
  111. trains, and headways. MTR includes East Rail in its live Next Train API again
  112. (verified 22 November 2026); use the `hongkong-mtr-skill` `mtr_next_trains`
  113. tool for live departures. If MTR disables the EAL feed again (`NT-205`), quote
  114. the published headway instead of inventing a train.
  115. High-speed rail is different: `rail hsr` reads MTR's own timetable JSON and
  116. returns the actual scheduled departures from West Kowloon, with train number,
  117. departure and arrival times, journey time and intermediate stops. Filter with
  118. `--to` (station code, English name or Chinese name) and cap the table with
  119. `--limit`; `--json` returns every matching departure and its stops. The
  120. source's effective dates are printed with the table.
  121. These are scheduled times, not live running or seat availability. 12306 is the
  122. booking authority, so check it for tickets and disruption before travelling.
  123. Fares and seat counts are deliberately not invented here.
  124. ## MCP
  125. ```bash
  126. $BIN mcp
  127. ```
  128. ```json
  129. {
  130. "mcpServers": {
  131. "hongkong-chinabus": {
  132. "command": "/absolute/path/to/hkchinabus",
  133. "args": ["mcp"]
  134. }
  135. }
  136. }
  137. ```
  138. Tools:
  139. | Tool | Arguments |
  140. | --- | --- |
  141. | `border_wait_times` | `{ "point"?: string }` |
  142. | `search_cross_border_coaches` | `{ "from": string, "to": string, "date"?: "YYYY-MM-DD", "limit"?: number }` |
  143. | `cross_border_ferry_board` | `{ "port"?: string, "terminal"?: "cft"\|"mft", "direction"?: "arrival"\|"departure" }` |
  144. | `cross_border_rail_info` | `{ "mode": "east-rail"\|"hsr", "destination"?: string, "limit"?: number }` |
  145. The server speaks JSON-RPC 2.0 over stdio, one message per line, and implements
  146. `initialize`, `ping`, `tools/list` and `tools/call`.
  147. ## Cautions
  148. - Queue minutes are Immigration Department bands, not a stopwatch. A coach
  149. arrival at the boundary can change the picture within minutes.
  150. - Having a coach ticket does not guarantee a seat on a earlier sailing, and
  151. boundary queues are separate from the coach journey.
  152. - Visa and entry requirements are outside this skill. Check the mainland,
  153. Macao and Hong Kong immigration authorities before travel.
  154. - High-speed rail times are the published schedule, not live running or seat
  155. availability. For tickets and disruption, use 12306 or the MTR app.
  156. - Do not present this as an official channel of ImmD, MTR, GoByBus or the
  157. Marine Department.
  158. ## Sources
  159. - Immigration Department queue times:
  160. `https://secure1.info.gov.hk/immd/mobileapps/2bb9ae17/data/CPQueueTimeR.json`
  161. and `CPQueueTimeV.json`
  162. - GoByBus: `https://www.gobybus.hk/` route directory and
  163. `POST https://www.gobybus.hk/zh/getSchedule.php`
  164. - Marine Department cross-boundary ferries:
  165. `https://crossboundaryferryservices.mardep.gov.hk/en/`
  166. - MTR high-speed rail timetable:
  167. `https://www.highspeed.mtr.com.hk/res/content/app/XRL_content_Timetable.json`
  168. (human page: `https://www.highspeed.mtr.com.hk/en/ticket/timetable.html`)
  169. - MTR high-speed rail station names:
  170. `https://www.highspeed.mtr.com.hk/res/content/XRL_content_TripPlanning.json`
README.md · README · 232 lines · 1 finding marked
  1. # hongkong-chinabus-skill
  2. Hong Kong cross-border travel in one Rust CLI and MCP server:
  3. - **Border queues** — live Immigration Department wait times at all nine land
  4. control points, split by residents and visitors, arrivals and departures.
  5. - **Cross-border coaches** — live GoByBus departures, prices and seat counts
  6. between Hong Kong and Shenzhen, Guangzhou, Macao, Zhuhai and beyond.
  7. - **Cross-boundary ferries** — the Marine Department berthing board for China
  8. Ferry Terminal and Macau Ferry Terminal.
  9. - **Rail** — East Rail service to Lo Wu and Lok Ma Chau, and the official MTR
  10. high-speed rail timetable from West Kowloon with exact scheduled departures.
  11. No API keys, no accounts, no scraping of booking pages. Data comes from
  12. official government feeds and GoByBus's public schedule endpoint.
  13. ## Install
  14. **Agent skill** — installs `SKILL.md` and the binary bootstrap script:
  15. ```bash
  16. npx skills add hongkong-ai-labs/hongkong-chinabus-skill
  17. npx skills update # refresh the installed skill later
  18. ```
  19. **Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or
  20. aarch64, static musl), checksum-verified, into `~/.local/bin`:
  21. ```bash
  22. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-chinabus-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 30 on GitHub
  23. ```
  24. **From source** — Rust 1.89 or newer:
  25. ```bash
  26. git clone https://github.com/hongkong-ai-labs/hongkong-chinabus-skill
  27. cd hongkong-chinabus-skill
  28. cargo install --path . --locked
  29. # or directly from GitHub:
  30. cargo install --git https://github.com/hongkong-ai-labs/hongkong-chinabus-skill --locked
  31. # or: cargo build --release --locked # target/release/hkchinabus
  32. ```
  33. Verify:
  34. ```console
  35. $ hkchinabus --version
  36. ```
  37. ## Usage
  38. ```bash
  39. hkchinabus borders
  40. hkchinabus borders --point "Shenzhen Bay"
  41. hkchinabus coaches --list
  42. hkchinabus coaches --from "China HK City"
  43. hkchinabus coaches --from "China HK City" --to "MGM Cotai" --date 2026-11-22
  44. hkchinabus coaches --from 14905 --to "Hong Kong Airport" --json
  45. hkchinabus ferries
  46. hkchinabus ferries --port Macao --terminal mft
  47. hkchinabus rail east-rail --station low
  48. hkchinabus rail hsr --to "Guangzhou South" --limit 12
  49. hkchinabus rail hsr --to "Shenzhen North" --json
  50. hkchinabus update --check
  51. ```
  52. Add `--json` before the subcommand for structured output:
  53. ```bash
  54. hkchinabus --json borders
  55. hkchinabus --json ferries --port Shekou
  56. ```
  57. ## What the data means
  58. `borders` prints bands rather than minutes because that is what ImmD
  59. publishes: `0` normal (under about 15 minutes), `1` busy (15–30), `2` very busy
  60. (30–60), `3` very busy (over 60), `99` closed or not in service. A `99` before
  61. opening or after closing is expected.
  62. `coaches` resolves station names against GoByBus's own directory. If a name is
  63. shared by several stations it lists the ids rather than guessing. GoByBus
  64. opens sales a few weeks ahead, so an empty result may mean "not on sale yet".
  65. Prices and seat counts are live and can change.
  66. `ferries` shows berthing movements, not ticket availability. The board is
  67. cached for 90 seconds and may still show the last sailings after service ends.
  68. East Rail here is reference data. MTR's live Next Train API includes East Rail
  69. again (verified 22 November 2026), so use `mtr_next_trains` from
  70. `hongkong-mtr-skill` for live EAL departures. If MTR disables the EAL feed
  71. (`NT-205`), the CLI reports the service pattern rather than inventing a train.
  72. `rail hsr` reads MTR's own timetable JSON and prints the actual scheduled
  73. departures from West Kowloon: train number, departure, arrival, duration and
  74. intermediate stops. `--to` accepts a station code, English or Chinese name;
  75. `--limit` caps the table; `--json` returns every match. These are scheduled
  76. times, not live running or seat availability. 12306 remains the booking
  77. authority, and fares/seat counts are not invented.
  78. ## MCP
  79. ```json
  80. {
  81. "mcpServers": {
  82. "hongkong-chinabus": {
  83. "command": "/absolute/path/to/hkchinabus",
  84. "args": ["mcp"]
  85. }
  86. }
  87. }
  88. ```
  89. Register it with any MCP client:
  90. ```bash
  91. npx add-mcp "$(command -v hkchinabus) mcp" --name hongkong-chinabus -a claude-code -a codex -a cursor -y
  92. claude mcp add hongkong-chinabus -- hkchinabus mcp
  93. codex mcp add hongkong-chinabus -- hkchinabus mcp
  94. ```
  95. `add-mcp` detects the client configuration files in the current project; add
  96. `-g` for a global install. `$(command -v hkchinabus)` keeps the entry correct
  97. when the binary is on `PATH`; substitute an absolute path if your client does
  98. not inherit the shell `PATH`.
  99. Tools: `border_wait_times`, `search_cross_border_coaches`,
  100. `cross_border_ferry_board`, `cross_border_rail_info`. See
  101. [`SKILL.md`](SKILL.md) for argument schemas and agent guidance.
  102. ## Run modes and deployment
  103. | Mode | Start with | Use for |
  104. | --- | --- | --- |
  105. | CLI | `hkchinabus <command>` | Interactive use and shell scripts |
  106. | JSON | `<command>` with `--json` | `jq`, automation, other programs |
  107. | MCP stdio | `hkchinabus mcp` | Desktop and CLI MCP clients |
  108. | Container | `docker run --rm -i hkchinabus mcp` | No local Rust toolchain |
  109. ### MCP and authentication
  110. This server is **stdio-only**: the client launches the process and speaks MCP
  111. over stdin/stdout. There is no listening port, so there is no network
  112. authentication layer and no API-key setting. Optional API keys in this project
  113. family apply only to servers that expose an HTTP transport. Keep the process
  114. local and let the MCP client manage it.
  115. Typical client entry:
  116. ```json
  117. {
  118. "mcpServers": {
  119. "hongkong-chinabus-skill": {
  120. "command": "hkchinabus",
  121. "args": ["mcp"]
  122. }
  123. }
  124. }
  125. ```
  126. If the client does not inherit `PATH`, use the absolute installed path.
  127. ### Docker and Apple container
  128. ```bash
  129. docker build -t hkchinabus .
  130. docker run --rm hkchinabus --help
  131. docker run --rm -i hkchinabus mcp # stdio MCP
  132. docker compose run --rm stdio # same, through Compose
  133. ```
  134. Apple's `container` runtime uses the same OCI image:
  135. ```bash
  136. container build -t hkchinabus .
  137. container run --rm hkchinabus --help
  138. container run --rm -i hkchinabus mcp
  139. ```
  140. The runtime image contains the release binary and CA certificates, runs as a
  141. non-root user, and defaults to `--help` so a bare `docker run` is harmless.
  142. ### Cloudflare and WASM
  143. There is no Worker or WASM deployment. The binary talks directly to upstream
  144. HTTP APIs over TLS and uses a Tokio runtime; packaging it as a stdio server is
  145. the supported integration. A Worker would need a separate HTTP/JavaScript
  146. adapter and is out of scope for this repo.
  147. ### Releases
  148. Pushing a `v*` tag runs the release workflow, which checks the tag against
  149. `Cargo.toml` and `CHANGELOG.md`, builds four targets, smoke-tests native
  150. binaries and publishes:
  151. - `hkchinabus-<tag>-<target>.tar.gz` for macOS and static Linux
  152. - `SHA256SUMS` covering every tarball
  153. `scripts/install.sh` downloads the latest release, verifies its checksum and
  154. falls back to `cargo build --release --locked` when no release is available.
  155. `just tag X.Y.Z` creates the annotated tag locally; `just release X.Y.Z` tags
  156. and pushes to trigger the workflow.
  157. ## Development
  158. ```bash
  159. just # fmt check, clippy with -D warnings, tests
  160. just skill-check # validate SKILL.md and shell syntax
  161. just container # build the image and print CLI help
  162. cargo test
  163. cargo clippy -- -D warnings
  164. cargo fmt --check
  165. ```
  166. `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
  167. `clippy`, so `rustup` sets contributors up automatically. `just doc`
  168. builds the API documentation. See `CONTRIBUTING.md` for the full check
  169. list and the signed-commit requirement.
  170. The parsers for the GoByBus directory and the Marine Department board are
  171. covered by unit tests; the live endpoints are exercised manually because they
  172. change during the day.
  173. ## Licence
  174. MIT. This is an independent project, not affiliated with the Hong Kong
  175. government, MTR, GoByBus or any ferry operator.

Ratings and comments

Sign in to rate this skill.

Sign in

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