Skip to content
Back to search

hongkong-jockeyclub-skill

Hong Kong Jockey Club data — horse racing fixtures, race cards, runners, jockeys, trainers, horse profiles, barriers, live tote odds, historical results, dividends and incidents, HKJC football matches and odds, plus Mark Six draw results, jackpots, prize divisions and number frequency. Use for questions about Hong Kong racing, Sha Tin, Happy Valley, Mark Six, 六合彩, race results, football or lottery numbers.

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

HTML

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

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

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

Verify:

$ hkjc --version

`hkjc update` detects whether the binary came from cargo, the release installer, a source checkout or Homebrew, and updates with that same method. `hkjc update --check` only reports.

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 · 214 lines · 1 finding marked
  1. ---
  2. name: hongkong-jockeyclub-skill
  3. description: Hong Kong Jockey Club data — horse racing fixtures, race cards, runners, jockeys, trainers, horse profiles, barriers, live tote odds, historical results, dividends and incidents, HKJC football matches and odds, plus Mark Six draw results, jackpots, prize divisions and number frequency. Use for questions about Hong Kong racing, Sha Tin, Happy Valley, Mark Six, 六合彩, race results, football or lottery numbers.
  4. license: MIT
  5. ---
  6. # Hong Kong Jockey Club
  7. `hkjc` is a Rust CLI and MCP server for Hong Kong Jockey Club horse racing,
  8. football and Mark Six. It needs no API key and no account. It is an independent,
  9. unofficial project.
  10. Use it when the user asks about:
  11. - today's or the current Hong Kong race meeting, races and post times
  12. - a race card: runners, horse names, jockeys, trainers, barriers, weights,
  13. ratings and recent form
  14. - live tote odds for a race (WIN, PLA, QIN, QPL, FCT, TCE, TRI, FF, QTT, CWA…)
  15. - a past race result: finishing order, lengths behind, times, starting odds,
  16. dividends and stewards' incidents
  17. - the season fixture list, including future race meetings weeks ahead
  18. - a jockey, trainer or horse profile: age, background, season statistics and
  19. recent form
  20. - HKJC football: match list, status, scores, HAD odds and full odds boards
  21. - Mark Six: winning numbers, extra number, jackpot, turnover, prize divisions,
  22. hot and cold numbers, odd/even split and average sum
  23. It covers the Club's three betting products, **horse racing**, **football** and
  24. **Mark Six**. It does not cover account balances, betting slips or placing
  25. bets.
  26. ## Before first use
  27. ```console
  28. $ bash scripts/ensure-binary.sh
  29. /Users/you/.local/bin/hkjc
  30. ```
  31. Use the printed path:
  32. ```bash
  33. BIN="$(bash scripts/ensure-binary.sh)"
  34. ```
  35. It checks `$HKJC_BIN`, `hkjc` on `PATH`, `scripts/install.sh`, then
  36. `cargo build --release --locked` in the repo root.
  37. ### Install the binary directly
  38. `npx skills add` installs the skill files. If the binary is missing, install it
  39. with the release installer or cargo:
  40. ```bash
  41. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-jockeyclub-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 54 on GitHub
  42. # or
  43. cargo install --git https://github.com/hongkong-ai-labs/hongkong-jockeyclub-skill --locked
  44. ```
  45. Register it with any MCP client:
  46. ```bash
  47. npx add-mcp "$(command -v hkjc-mcp)" --name hongkong-jockeyclub -a claude-code -a codex -a cursor -y
  48. claude mcp add hongkong-jockeyclub -- hkjc-mcp
  49. codex mcp add hongkong-jockeyclub -- hkjc-mcp
  50. ```
  51. `add-mcp` detects the client configuration files in the current project; add
  52. `-g` for a global install. `$(command -v hkjc-mcp)` keeps the entry correct
  53. when the binary is on `PATH`; substitute an absolute path if your client does
  54. not inherit the shell `PATH`.
  55. ## CLI
  56. ```bash
  57. $BIN meetings # current meeting(s), races and post times
  58. $BIN meetings --venue ST
  59. $BIN card --race 7 # runners for race 7
  60. $BIN card --race 1 --json
  61. $BIN odds --race 1 --types WIN,PLA,QIN
  62. $BIN results --date 2026-11-18 --venue HV --race 4
  63. $BIN fixtures # race meetings in the next 90 days
  64. $BIN fixtures --all # the whole season
  65. $BIN lookup Purton # find a jockey, trainer or horse
  66. $BIN profile jockey PZ # official profile
  67. $BIN profile trainer TKH --json
  68. $BIN profile horse HK_2024_K392
  69. $BIN football --limit 20 # matches with HAD odds
  70. $BIN football --tournament "Premier"
  71. $BIN football-match 50079900 # full odds board
  72. $BIN marksix --draws 10 # last 10 draws
  73. $BIN marksix --from 2026-11-01 --to 2026-11-21
  74. $BIN marksix-latest # latest draw with prize breakdown
  75. $BIN marksix-stats --draws 100 # number frequency
  76. $BIN mcp
  77. $BIN update --check
  78. ```
  79. Add `--json` to any command for structured output.
  80. `update` detects whether the binary came from cargo, the release installer, a
  81. source checkout or Homebrew, and updates with that same method.
  82. `update --check` only reports.
  83. ### Venue codes
  84. | Code | Venue |
  85. | --- | --- |
  86. | `ST` | Sha Tin |
  87. | `HV` | Happy Valley |
  88. | `CH` | Conghua |
  89. | `S1`–`S9` | Simulcast meetings |
  90. ### What a race card contains
  91. | Field | Meaning |
  92. | --- | --- |
  93. | `no`, `horse_no` | Race card number |
  94. | `horse`, `horse_zh` | English and Chinese horse name |
  95. | `horse_id` | HKJC horse id |
  96. | `jockey`, `trainer` | Names as declared |
  97. | `draw` | Barrier draw |
  98. | `weight` | Handicap weight |
  99. | `rating` | Current rating |
  100. | `last_6_runs` | Finishing positions, newest first |
  101. | `gear` | Declared gear |
  102. | `win_odds` | Tote win odds when selling has started |
  103. | `status` | Declared, scratched, standby, etc. |
  104. ## MCP
  105. ```json
  106. {
  107. "mcpServers": {
  108. "hongkong-jockeyclub": {
  109. "command": "/absolute/path/to/hkjc-mcp",
  110. "args": []
  111. }
  112. }
  113. }
  114. ```
  115. Tools:
  116. | Tool | Arguments |
  117. | --- | --- |
  118. | `hk_race_meetings` | `{ date?, venue? }` |
  119. | `hk_race_card` | `{ race?, date?, venue? }` |
  120. | `hk_race_odds` | `{ race?, types?, date?, venue? }` |
  121. | `hk_race_results` | `{ date?, venue?, race? }` |
  122. | `hk_race_fixtures` | `{ from?, to?, venue?, all? }` |
  123. | `hk_race_profile` | `{ kind, id }` — kind is `jockey`, `trainer` or `horse` |
  124. | `hk_race_lookup` | `{ query }` — name to profile id |
  125. | `hk_football_matches` | `{ from?, to?, tournament?, limit? }` |
  126. | `hk_football_match` | `{ id, types? }` |
  127. | `hk_marksix_results` | `{ draws?, from?, to? }` |
  128. | `hk_marksix_latest` | `{}` |
  129. | `hk_marksix_stats` | `{ draws? }` |
  130. ## Answering patterns
  131. - "What's on today?" → `meetings`; give venue, race numbers and post times.
  132. - "Who's running in race 7?" → `card --race 7`; list horse, jockey, trainer,
  133. draw and recent form.
  134. - "Who's favourite?" → `odds --race N --types WIN`; the `★` marks the hot
  135. favourite. Report odds as tote odds, not a prediction.
  136. - "When is the next race meeting?" → `fixtures`; give date, weekday and venue.
  137. Use `fixtures --all` for the full season.
  138. - "Who won race 4 at Happy Valley on 18 November?" → `results --date
  139. 2026-11-18 --venue HV --race 4`; give the first three, then dividends.
  140. - "Tell me about Zac Purton" → `lookup Purton`, then `profile jockey PZ`.
  141. - "What are Arsenal's odds?" → `football --tournament "Premier"`, then
  142. `football-match <id>` for the full board.
  143. - "Lucky Twenty's form" → `lookup "Lucky Twenty"`, then `profile horse <id>`.
  144. - "What were the Mark Six numbers?" → `marksix-latest` or `marksix --draws 5`.
  145. - "Which numbers are due?" → `marksix-stats --draws 100`. State clearly that
  146. draws are independent and frequency does not predict the next draw.
  147. - "How much is the jackpot?" → `marksix-latest`; the jackpot is the published
  148. snowball/jackpot figure, and the first-division dividend is separate.
  149. ## Cautions
  150. - Race meetings, declarations, odds and scratchings change constantly. Always
  151. call the tool for the current state; never reuse an earlier answer.
  152. - `meetings` covers only the meeting HKJC currently publishes. For any other
  153. date, including future meetings, use `fixtures`.
  154. - Historical results are only available for actual race days. A date with no
  155. meeting returns an error, not an empty result.
  156. - Odds are tote/dividend odds. They are not fixed-odds prices and do not
  157. guarantee a return.
  158. - Mark Six draws are random. Frequency statistics describe the past only.
  159. - The Mark Six history endpoint returns a capped recent window even when a
  160. larger count is requested; report the number of draws actually analysed. An
  161. explicit `--from`/`--to` range must span about three months or less.
  162. - With `--to` but no `--from`, the tool looks back 90 days.
  163. - Football coverage follows HKJC's own list. Kick-off times are Hong Kong time,
  164. and in-play odds change or close during a match.
  165. - This tool does not place bets, hold tickets or check account balances.
  166. - Not an official HKJC channel. Check the HKJC website or a betting branch for
  167. confirmation.
  168. ## Source
  169. - `https://info.cld.hkjc.com/graphql/base/` — the GraphQL API used by
  170. bet.hkjc.com for race cards, odds, results pools and Mark Six.
  171. - `https://racing.hkjc.com/racing/information/English/Racing/LocalResults.aspx`
  172. — published local race results and dividends.
  173. - `https://racing.hkjc.com/racing/information/English/Racing/Fixture.aspx`
  174. — the month-by-month fixture calendar.
  175. - `https://racing.hkjc.com/en-us/local/information/jockeyprofile`,
  176. `.../trainerprofile` and `.../horse` — official profiles.
  177. All are unofficial integrations. Responses are cached briefly in-process:
  178. 15–20 seconds for live racing data, 1 hour for fixtures and profiles, and
  179. 2 minutes for Mark Six history.
README.md · README · 216 lines · 1 finding marked
  1. # hkjc
  2. Hong Kong Jockey Club horse racing, football and Mark Six as a Rust CLI and MCP
  3. server.
  4. Reads the official, keyless data that powers bet.hkjc.com: race meetings, race
  5. cards, runners, live tote odds, football matches and odds, Mark Six draws and
  6. prize divisions. Historical race results, dividends, season fixtures and
  7. jockey, trainer and horse profiles are read from racing.hkjc.com.
  8. ## Install
  9. **Agent skill** — installs `SKILL.md` and the binary bootstrap script:
  10. ```bash
  11. npx skills add hongkong-ai-labs/hongkong-jockeyclub-skill
  12. npx skills update # refresh the installed skill later
  13. ```
  14. **Prebuilt binary** — macOS (Intel or Apple silicon) and Linux (x86_64 or
  15. aarch64, static musl), checksum-verified, into `~/.local/bin`:
  16. ```bash
  17. curl -fsSL https://raw.githubusercontent.com/hongkong-ai-labs/hongkong-jockeyclub-skill/main/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 24 on GitHub
  18. ```
  19. **From source** — Rust 1.89 or newer:
  20. ```bash
  21. git clone https://github.com/hongkong-ai-labs/hongkong-jockeyclub-skill
  22. cd hongkong-jockeyclub-skill
  23. cargo install --path . --locked
  24. # or directly from GitHub:
  25. cargo install --git https://github.com/hongkong-ai-labs/hongkong-jockeyclub-skill --locked
  26. # or: cargo build --release --locked # target/release/hkjc
  27. ```
  28. Verify:
  29. ```console
  30. $ hkjc --version
  31. ```
  32. `hkjc update` detects whether the binary came from cargo, the release
  33. installer, a source checkout or Homebrew, and updates with that same
  34. method. `hkjc update --check` only reports.
  35. ## CLI
  36. ```bash
  37. hkjc meetings
  38. hkjc meetings --venue ST
  39. hkjc card --race 7
  40. hkjc odds --race 1 --types WIN,PLA,QIN
  41. hkjc results --date 2026-11-18 --venue HV --race 4
  42. hkjc fixtures
  43. hkjc fixtures --all
  44. hkjc lookup Purton
  45. hkjc profile jockey PZ
  46. hkjc profile horse HK_2024_K392
  47. hkjc football --limit 20
  48. hkjc football-match 50079900
  49. hkjc marksix --draws 10
  50. hkjc marksix --from 2026-11-01 --to 2026-11-21
  51. hkjc marksix-latest
  52. hkjc marksix-stats --draws 100
  53. hkjc mcp
  54. hkjc update --check
  55. ```
  56. Add `--json` for structured output.
  57. ## MCP
  58. ```json
  59. {
  60. "mcpServers": {
  61. "hongkong-jockeyclub": { "command": "hkjc-mcp", "args": [] }
  62. }
  63. }
  64. ```
  65. Register it with any MCP client:
  66. ```bash
  67. npx add-mcp "$(command -v hkjc-mcp)" --name hongkong-jockeyclub -a claude-code -a codex -a cursor -y
  68. claude mcp add hongkong-jockeyclub -- hkjc-mcp
  69. codex mcp add hongkong-jockeyclub -- hkjc-mcp
  70. ```
  71. `add-mcp` detects the client configuration files in the current project; add
  72. `-g` for a global install. `$(command -v hkjc-mcp)` keeps the entry correct
  73. when the binary is on `PATH`; substitute an absolute path if your client does
  74. not inherit the shell `PATH`.
  75. Tools: `hk_race_meetings`, `hk_race_card`, `hk_race_odds`, `hk_race_results`,
  76. `hk_race_fixtures`, `hk_race_profile`, `hk_race_lookup`, `hk_football_matches`,
  77. `hk_football_match`, `hk_marksix_results`, `hk_marksix_latest`,
  78. `hk_marksix_stats`.
  79. ## Data
  80. - `https://info.cld.hkjc.com/graphql/base/` — race meetings, race cards,
  81. runners, tote odds, Mark Six.
  82. - `https://racing.hkjc.com/racing/information/English/Racing/LocalResults.aspx`
  83. — historical race results and dividends.
  84. - `https://racing.hkjc.com/racing/information/English/Racing/Fixture.aspx`
  85. — the season fixture calendar.
  86. - `https://racing.hkjc.com/en-us/local/information/` — jockey, trainer and horse
  87. profiles.
  88. `meetings` covers only the meeting HKJC currently publishes; `fixtures` covers
  89. the season, including future meetings. Historical results need an actual race
  90. day. Mark Six history is a capped recent window, and an explicit date range must
  91. span about three months or less. Odds, declarations and results change; check
  92. HKJC for confirmation.
  93. ## Run modes and deployment
  94. | Mode | Start with | Use for |
  95. | --- | --- | --- |
  96. | CLI | `hkjc <command>` | Interactive use and shell scripts |
  97. | JSON | `<command>` with `--json` | `jq`, automation, other programs |
  98. | MCP stdio | `hkjc-mcp` (starts directly) or `hkjc mcp` | Desktop and CLI MCP clients |
  99. | Container | `docker run --rm -i hkjc mcp` | No local Rust toolchain |
  100. ### MCP and authentication
  101. This server is **stdio-only**: the client launches the process and speaks MCP
  102. over stdin/stdout. There is no listening port, so there is no network
  103. authentication layer and no API-key setting. Optional API keys in this project
  104. family apply only to servers that expose an HTTP transport. Keep the process
  105. local and let the MCP client manage it.
  106. Typical client entry:
  107. ```json
  108. {
  109. "mcpServers": {
  110. "hongkong-jockeyclub-skill": {
  111. "command": "hkjc-mcp",
  112. "args": ["mcp"]
  113. }
  114. }
  115. }
  116. ```
  117. If the client does not inherit `PATH`, use the absolute installed path.
  118. ### Docker and Apple container
  119. ```bash
  120. docker build -t hkjc .
  121. docker run --rm hkjc --help
  122. docker run --rm -i hkjc mcp # stdio MCP
  123. docker compose run --rm stdio # same, through Compose
  124. ```
  125. Apple's `container` runtime uses the same OCI image:
  126. ```bash
  127. container build -t hkjc .
  128. container run --rm hkjc --help
  129. container run --rm -i hkjc mcp
  130. ```
  131. The runtime image contains the release binary and CA certificates, runs as a
  132. non-root user, and defaults to `--help` so a bare `docker run` is harmless.
  133. ### Cloudflare and WASM
  134. There is no Worker or WASM deployment. The binary talks directly to upstream
  135. HTTP APIs over TLS and uses a Tokio runtime; packaging it as a stdio server is
  136. the supported integration. A Worker would need a separate HTTP/JavaScript
  137. adapter and is out of scope for this repo.
  138. ### Releases
  139. Pushing a `v*` tag runs the release workflow, which checks the tag against
  140. `Cargo.toml` and `CHANGELOG.md`, builds four targets, smoke-tests native
  141. binaries and publishes:
  142. - `hkjc-<tag>-<target>.tar.gz` for macOS and static Linux, containing both
  143. `hkjc` and `hkjc-mcp`
  144. - `SHA256SUMS` covering every tarball
  145. `scripts/install.sh` downloads the latest release, verifies its checksum and
  146. falls back to `cargo build --release --locked` when no release is available.
  147. `just tag X.Y.Z` creates the annotated tag locally; `just release X.Y.Z` tags
  148. and pushes to trigger the workflow.
  149. ## Development
  150. ```bash
  151. just # fmt check, clippy with -D warnings, tests
  152. just skill-check # validate SKILL.md and shell syntax
  153. just container # build the image and print CLI help
  154. cargo test --all --locked
  155. cargo clippy --all-targets --locked -- -D warnings
  156. cargo fmt --all -- --check
  157. ```
  158. `rust-toolchain.toml` pins the stable toolchain with `rustfmt` and
  159. `clippy`, so `rustup` sets contributors up automatically. `just doc`
  160. builds the API documentation. See `CONTRIBUTING.md` for the full check
  161. list and the signed-commit requirement.
  162. CI runs the same checks. Dependabot proposes weekly Cargo and GitHub Actions
  163. updates, and the audit workflow checks the lockfile against the RustSec
  164. advisory database.
  165. ## Licence
  166. MIT. The data remains subject to the Hong Kong Jockey Club's terms of use.

Ratings and comments

Sign in to rate this skill.

Sign in

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