hktvmall-mcp

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.

Tools

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

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 account its connection belongs to, 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, and give clients the bearer (Authorization: Bearer <token>).

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 (experimental)

One server can also hold other people's HKTVmall accounts, each person acting only on their own. They add the server as a connector in Claude or ChatGPT and press Connect: the server's own OAuth sign-in asks for an invite code you gave them, then shows them HKTVmall's real login page through a browser running next to the server (ghcr.io/benjamin-di/hktvmall-mcp-login-browser, viewed through noVNC; nothing on the login is automated). Their sessions are stored encrypted (HKTVMALL_SESSION_KEY). Invites and accounts are managed with hktvmall-mcp admin invite LABEL | invites | revoke PREFIX | accounts | disconnect ID. This needs a public HTTPS address (HKTVMALL_PUBLIC_URL) and the login browser service (HKTVMALL_LOGIN_URL, HKTVMALL_LOGIN_TOKEN). All accounts share the server's IP address, so requests are paced and budgeted for all of them together. Wrong invite codes are rate-limited per client address from X-Forwarded-For: the reverse proxy in front must overwrite that header with the client's address, not append to it.

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.