hktvmall-mcp

Read the permissions model.

An MCP server for HKTVmall, Hong Kong's online mall and supermarket. It lets an AI assistant (Claude, ChatGPT, Cursor, ...) search HKTVmall for a whole shopping list, compare prices and unit prices, show product cards with photos, read your order history and set quantities in your real basket. You pay yourself, on HKTVmall: the server cannot place, pay for or change an order.

Unofficial. Not affiliated with or endorsed by HKTVmall or Hong Kong Television Network Limited. HKTVmall has no public API; this server uses the same endpoints HKTVmall's own website uses, gently and only when you ask. Use it with your own account for your own shopping; HKTVmall's terms and conditions apply to you.

Requirements

• A connection from Hong Kong: HKTVmall answers connections from elsewhere with errors.

• An HKTVmall account for the basket and order history (search works without one).

• uv (it fetches Python 3.12 if needed), or Docker for a server.

• Google Chrome for signing in (or Chromium, see Signing in).

Quick start

1. Sign in once. A browser window opens on HKTVmall's own login page; log in as usual (HKTVmall's own checks included). It closes once you are signed in, and the session is saved for the server.

   uvx --from "hktvmall-mcp[login]" hktvmall-mcp login

2. Add the server to your client. It runs over stdio, started by the client:

   • Claude Code: claude mcp add hktvmall -- uvx hktvmall-mcp

   • Claude Desktop, Cursor and most other clients: add to the client's MCP configuration

     {
       "mcpServers": {
         "hktvmall": {
           "command": "uvx",
           "args": ["hktvmall-mcp"]
         }
       }
     }

3. Ask. "Put milk, a dozen eggs and some bananas in my HKTVmall basket", "What did I order last month? Add the same toilet paper again", "Which of these olive oils is cheapest per 100 ml?".

These commands run the latest release from PyPI (hktvmall-mcp); write hktvmall-mcp==X.Y.Z to stay on a release, or --from git+https://github.com/benjamin-di/hktvmall-mcp-server for the latest code.

Related MCP server: Rohlik MCP Server

Tools

Money is {"cents": 12990, "display": "HK$129.90"}. Errors are {"error": {code, next_step, retryable, action}}: the next_step text tells the assistant what to do, and action is retry_later, human_account_check, repair_local_infrastructure or none. A call that changed anything never returns an error: it reports each change's outcome.

On hosted people-mode servers, hktv_get_cart also returns connection (owner, shared) and account_context. The latter must accompany basket updates; account choice remains a human action on My connections.

Safety

Enforced in code and pinned by tests/test_safety.py:

• No money moves. No endpoint for placing, paying for, changing or cancelling an order, and none for vouchers, credit, addresses, profiles, wish lists or delivery-slot changes, exists in the code. You check out on HKTVmall.

• Only HKTVmall. Requests go only to www.hktvmall.com, its search service and its public review service, to an allowlist of paths; redirects that leave those hosts are refused. The product cards load photos from HKTVmall's image servers only and connect nowhere.

• The truth is the basket. HKTVmall's replies to basket changes are not always true (an item silently dropped, a quantity silently capped), so every change is read back and reported as HKTVmall then shows it.

• Gentle. One request at a time, at most about three a second, a daily request budget, and a pause of 5 minutes (30 when it repeats) whenever HKTVmall pushes back.

• Your account only. Each call acts for the caller's own HKTVmall connection, or the one a household member chose to share with them, never one named in a tool argument. Product names, descriptions and reviews are treated as data, not instructions.

Privacy

Everything stays on the computer that runs the server, in its state folder (~/.local/state/hktvmall-mcp on Linux, ~/Library/Application Support/hktvmall-mcp on macOS, %LOCALAPPDATA%\hktvmall-mcp on Windows, /state in the container; HKTVMALL_STATE_DIR overrides it):

Nothing is sent anywhere except HKTVmall. Logs (stderr) never contain cookies, search terms or HKTVmall's error text; a basket change HKTVmall did not apply as asked is logged with its product id and quantities, for diagnosis. The server never reads your address or payment details (the delivery-slot lookup reads only the delivery zone of your first address). hktvmall-mcp logout deletes the session and the browser profile.

Signing in

hktvmall-mcp login opens HKTVmall's login page in your installed Google Chrome, using a separate profile in the state folder. You do every step yourself; nothing is clicked or typed for you. When HKTVmall's own home page says you are signed in, the session is saved and the window closes. A running server picks up the new session with its next call.

• No Chrome? Run patchright install chromium, then hktvmall-mcp login --browser chromium, both the same way as in the Quick start (uvx --from "hktvmall-mcp[login]" ...).

• HKTVmall decides how long a session lasts. When it ends, tools return session_expired: sign in again.

• hktvmall-mcp status shows whether the saved session is signed in, without asking HKTVmall anything.

Running it as a server

For remote clients (claude.ai, ChatGPT and the Claude and ChatGPT apps reach connectors over HTTPS) or a shared home server, run it over streamable HTTP. It refuses to start without a bearer token:

docker run -d --name hktvmall-mcp -p 127.0.0.1:8000:8000 \
  -e MCP_BEARER_TOKEN="$(openssl rand -hex 32)" \
  -v hktvmall-state:/state \
  ghcr.io/benjamin-di/hktvmall-mcp-server:latest

or MCP_BEARER_TOKEN=... uvx hktvmall-mcp serve --port 8000. The MCP endpoint is /mcp; /health is open for health checks (the image's HEALTHCHECK runs hktvmall-mcp health). Put it behind your own HTTPS reverse proxy to reach it from outside. In a private single-account setup, the bearer (Authorization: Bearer <token>) grants that account's complete backend access. For hosted/shared use, keep it server-only in an authenticating gateway; clients authenticate to the gateway separately as described below.

The server still needs a signed-in session in its state folder. Sign in with hktvmall-mcp login on a computer with a screen in the same network and copy that computer's session.json into the server's state folder (the volume above); the server adopts it on its next call. HKTVmall decides how long a session lasts; if it ends sooner on the server, sign in again the same way.

Hosting several people

Behind an authenticating gateway, the server hosts several people. The gateway admits MCP clients, supplies the server-only bearer and sets the header named by HKTVMALL_TRUSTED_ACCOUNT_HEADER to the caller's verified, administrator-owned person id (lowercase letters, digits, _ and -). Keep the backend bearer private to the gateway; a request without it, or with a missing, repeated or malformed person, gets not_connected and never another person's account.

People come from the identity provider. Whoever the gateway admits (for example, members of an mcp-hktvmall group) has a record: the first call or Connections sign-in of a person creates people/<person>/. There is no per-server list to keep; removing someone from the group removes their access. A folder whose connection record is missing (a lost or replaced volume) refuses rather than starting over.

Connect your own account, or use one shared with you. My connections is <HKTVMALL_PUBLIC_URL>/connections/, which hktv_connect returns. They authenticate through the configured OIDC provider and log in on HKTVmall's own page in a browser window the server shows them; nothing about the login is automated. The first HKTVmall account a person connects stays theirs: a reconnect must be the same account, and an HKTVmall account another person connected is refused, so nobody signs in to someone else's account.

Sharing and selection are separate choices. A household often shops in one basket. The person who connected it can share it with others on My connections. Recipients can read and change that basket; order-history access is optional and off by default for new shares. They never receive the password and cannot reconnect, disconnect or share the owner's connection. The recipient explicitly chooses Use [owner]'s account; an offer never changes routing.

A person can keep their own connection and several shared offers, with one selected shopping account. Use my account switches back without another provider sign-in. Their own connection stays connected while they use a shared account, including for people they share with. Disconnecting their own account does not prevent choosing a shared account. Changing the owned provider account is a separate operation and is not supported.

To share a household account:

1. Everyone opens My connections from hktv_connect and signs in with their own identity-provider login. This makes them appear in the sharing list; recipients do not need to connect an HKTVmall account.

2. The owner connects HKTVmall, then uses Shared with → Share beside the recipient. Optionally enable Also allow reading order history. Person IDs distinguish identical display names.

3. The recipient opens Shared accounts available to me, reads the access scope and presses Use [owner]'s account. The page and basket result identify which account their assistant uses.

Stop sharing removes the owner's grant. Leave shared account removes the recipient's access and clears their selection if they were using it. Neither operation selects another account. Disconnect removes the owner's stored login, stopping that connection for all its users until the owner reconnects. Its confirmation explains who is affected. Sharing controls remain available during reconnects, independently of which account the owner uses.

Calls never fall back: an expired or disconnected shared account needs its owner to reconnect (owner_reconnect); removed or changed access needs an explicit new choice (shared_access_removed). Reissuing a grant does not restore a previous selection. Updating a grant's history permission also requires the recipient to choose the updated offer. Previously admitted work can finish on its captured account; switching never redirects it.

In people mode, read hktv_get_cart before editing. Pass its opaque account_context to hktv_update_cart. A switch (including away and back), sharing change or reconnect invalidates the context; a stale or missing context returns account_changed before sending any provider request. Re-read the basket, check its owner and reassess the request. This guards account selection, not basket contents changed by someone in the provider's app. Single-account and stdio clients do not need this argument.

If someone is missing from the sharing list, they must open My connections once or make an admitted MCP call. Single-account/stdio servers have no sharing page; hosted sharing requires people mode and the browser routes below.

Register exactly <HKTVMALL_PUBLIC_URL>/connections/callback with the OIDC provider; require its signed group and the administrator-controlled person claim. The first explicit connection, selection or sharing action pins the person's issuer and immutable subject; status reads never do. Connect and Share require a fresh authentication (within five minutes). Every page, form, viewer asset and WebSocket checks the person; forms carry the relevant connection, selection and grant revisions, so a stale form changes nothing. A link, MCP token or forwarded header cannot substitute for the browser sign-in. Missing OIDC settings refuse browser-enabled HTTP startup. Connecting grants no new assistant permissions; browser Sign out ends only that browser session.

The login service (HKTVMALL_LOGIN_URL, HKTVMALL_LOGIN_TOKEN) shows HKTVmall's own page through noVNC and automates no credential entry. A wrong or failed sign-in keeps the accepted session; closing the page keeps a resumable window, and a completed save continues without the page. scripts/paste_e2e.py verifies signed synthetic OIDC, owner isolation, the real Xvfb/x11vnc/noVNC viewer and clipboard input, page-close recovery, saving, sharing selection, mobile/keyboard switching, revocation, leaving, disconnect and logout. It never contacts HKTVmall.

Disconnect persists a barrier before cancelling windows or deleting the sealed session. It blocks new calls, cached clients, cookie refresh and keep-alive across restarts; the record, its sharing, budgets and caches stay. Reconnect advances the epoch and session generation. hktvmall-mcp admin accounts lists people (masked emails, state, sharing) and hktvmall-mcp admin disconnect PERSON uses the same disconnect path.

Hosted upgrades migrate existing people controls to version 2 while preserving routing and existing history grants. Stop traffic while updating all readers and writers. Older images refuse the new controls and cannot be used as rollback targets after migration; see upgrade and recovery. Refresh cached MCP tool definitions so basket updates can supply account_context. The optional deep health check (hktv_status(check=true)) includes an order-history probe, so shared connections need history permission for it; ordinary status reads remain available with shopping access.

Forward only GET /connections/, /connections/status, /connections/login, /connections/callback, POST /connections/start, /connections/disconnect, /connections/share, /connections/unshare, /connections/leave, /connections/select, /connections/logout, and the /connect/<id> viewer shapes. Strip Authorization and forwarded identity headers on browser routes; preserve Cookie and Origin. Keep /mcp behind gateway admission. Releases before 0.14 read operator account and manager maps (HKTVMALL_CONNECTIONS_ACCOUNTS_FILE, HKTVMALL_CONNECTIONS_MANAGERS_FILE) and a default-account browser backend (HKTVMALL_DEFAULT_LOGIN_URL); these settings now refuse startup, and images before 0.14 are not rollback targets once people have records.

Pasting works in the login window: Ctrl+V (Cmd+V on a Mac) types the clipboard's text into HKTVmall's page, so a password manager's copy can be used (a small add-on to noVNC's viewer from signin-window, the library the login window is built on; up to 1000 characters the window's keyboard has, which covers ASCII; the text is never logged or kept). On a phone, noVNC's keyboard button opens the phone's keyboard, which pastes as usual. Passkeys do not work in a remote window: log in with a password or a code.

Run the login browser on a private network next to the server, never published to the internet: it listens on port 8080, refuses to start without HKTVMALL_LOGIN_TOKEN (at least 32 characters, the same value the server gets) and holds at most HKTVMALL_LOGIN_SLOTS (2) logins at a time, each ended after HKTVMALL_LOGIN_MINUTES (15) unfinished. The server's HKTVMALL_LOGIN_URL names it by host and port, such as http://hktvmall-mcp-login:8080.

Session snapshot (for operators)

Instead of its own session.json, the default account can read a session that another program keeps signed in and publishes as a file: set HKTVMALL_SESSION_SNAPSHOT (an absolute path, mounted read-only) and HKTVMALL_EXPECTED_EMAIL (the account it must belong to). The server never writes it; it adopts a file only when its generation is greater than the one it holds, and checks HKTVmall's home page before the first basket call of each generation. The file is JSON, at most 512 KiB:

{"schema": 1, "target": "hktvmall", "generation": 3, "email": "you@example.com",
 "user_agent": "Mozilla/5.0 ...", "verified_at": "2030-01-01T00:00:00+00:00",
 "cookies": [{"name": "JSESSIONID", "value": "...", "domain": "www.hktvmall.com", "path": "/",
              "secure": true, "expires": null}]}

expires is Unix seconds or null; it must contain a JSESSIONID for www.hktvmall.com. Symlinks, files that are not regular files and timestamps in the future are rejected. session.json uses the same format.

Configuration

Troubleshooting

How it works

HKTVmall has no public API, so the server speaks to the endpoints its website uses, over plain HTTP, with the cookies of a browser session you signed in to. docs/hktvmall-site.md records what is known about those endpoints and their quirks; docs/DESIGN.md explains the decisions. When HKTVmall changes its site, calls fail with schema_changed until the server is updated.

Development

See CONTRIBUTING.md. Tests never contact HKTVmall.

License

MIT.

Optional operator-owned account upkeep for a single-account server is documented in Account maintenance.