shopee-mcp

An MCP server for exploring Shopee — product search, prices, reviews, shops and flash sales — from any MCP client (Claude Desktop, Claude Code, etc.). Discovery only: no seller features.

Login required, read-only. Shopee blocks anonymous requests, so this unofficial server reads public data through your own logged-in browser session (see Why a browser?). Signed out it is read-only; signed in it also offers experimental account tools for your orders, cart, vouchers, likes and follows.

Full reference: Documentation · Changelog: CHANGELOG.md · Versioning & releases: docs/RELEASES.md

Tools

Tool annotations

Per the MCP annotations spec — every default tool is read-only, with no side effects.

Account mode (experimental)

When the saved session is logged in, the server also offers tools that work on your own account. When it isn’t, you get the read-only tools above and the account tools are hidden. The server checks the login in the background at startup and whenever check_login_status runs or a request reports a lapsed session, and tells your MCP client to refresh its tool list (notifications/tools/list_changed). Set SHOPEE_ACCOUNT_TOOLS=off to stay read-only even while logged in.

Read your account

Act on your account — these modify your Shopee account:

How they stay safe:

• Nothing checks out, pays, or touches addresses, payment methods, passwords, or chat. Order detail omits your address and phone number.
• Every action clicks Shopee’s own button on the real page (never a hand-crafted request), then reports only what Shopee’s response confirmed.
• They check the current state first — liking a liked product, or claiming a claimed voucher, changes nothing.
• They refuse rather than guess: a multi-variant listing needs an explicit modelId, add_to_cart verifies the quantity box shows exactly what you asked for and never falls back to “Buy Now”, and claim_shop_voucher only clicks when the page’s voucher buttons line up with the shop’s voucher list.

They drive Shopee’s UI, so a site redesign can break them — hence experimental. The cart tools build on @DystopiaOwO’s fork.

Why a browser?

Shopee does not expose an open API or server-rendered product HTML. Its /api/v4/* endpoints are guarded by an anti-fraud gate (error 90309999) that requires per-request signature headers (af-ac-enc-dat, x-sap-sec, …) minted by Shopee’s own obfuscated SDK. Plain fetch, headless Chromium, and even a hand-rolled fetch from inside the page all get rejected.

So this server:

1. Drives CloakBrowser — a Chromium with binary-level fingerprint patches — against a persistent profile you log into once.
2. Navigates to the real Shopee page and intercepts the response its own app fetches, so the request carries valid signatures.

The browser must run headed (Shopee detects headless); on a server use a virtual display (xvfb).

From npm (recommended)

npm install -g @bintangtimurlangit/shopee-mcp   # downloads the CloakBrowser binary (~200 MB, cached)

This puts two commands on your PATH: shopee-mcp (the server) and shopee-mcp-login (one-time login). Or run without installing: npx -y @bintangtimurlangit/shopee-mcp.

From source

git clone https://github.com/bintangtimurlangit/shopee-mcp.git
cd shopee-mcp
npm install          # also downloads the CloakBrowser binary (~200 MB, cached)
npm run build

1. Log in once

Shopee blocks anonymous requests, so you sign in one time. This saves a session to ~/.shopee-mcp/chrome-profile.

shopee-mcp-login     # global install — or, from a source checkout:  npm run login

• Opens a CloakBrowser window — log in, then press Enter.
• On a desktop / WSLg, the window appears normally.
• Re-run only when the session expires.

2. Register with your MCP client

The server launches a headed browser, so it needs a display. On a headless machine, wrap it with xvfb-run.

Claude Desktop / Claude Code mcpServers entry:

{
  "mcpServers": {
    "shopee": {
      "command": "xvfb-run",
      "args": ["-a", "shopee-mcp"]
    }
  }
}

On a machine with a real display, drop xvfb-run: "command": "shopee-mcp", "args": []. From a source checkout, use "command": "node", "args": ["/absolute/path/to/shopee-mcp/build/index.js"] (wrapped in xvfb-run on a headless box).

Configuration

All optional — see .env.example. Copy to .env to override.

Tool timings and client timeouts: see docs/CONFIGURATION.md.

Development

npm run lint         # eslint
npm run format       # prettier --write (format:check to verify)
npm run typecheck
npm run test:unit    # offline unit tests (no login/display needed)
npm test             # live smoke test (needs a display; use xvfb-run on servers)
npm run dev          # tsx watch

More detail: docs/DEVELOPMENT.md.

Troubleshooting

Caveats

• Login required. Shopee blocks anonymous browsing: with no session, get_shop_info still works and every other tool returns a friendly “run npm run login” prompt.
• Anti-bot is a moving target. The free CloakBrowser binary can go stale as Shopee updates detection; CloakBrowser Pro ships newer patches.
• Respect Shopee’s Terms of Service. This is for personal market exploration, not scraping at scale.
• Regions. Indonesia is the most tested; Malaysia, Singapore and Taiwan get the matching locale, timezone and currency automatically.

Contributing & security

CONTRIBUTING.md · SECURITY.md · Code of Conduct

License

MIT

---

Disclaimer

This is an unofficial project. It is not affiliated with, authorized, maintained, sponsored, or endorsed by Shopee or Sea Limited.

It works by driving a real logged-in browser session against Shopee’s web app, which can change without notice — a tool may break when Shopee updates its site or anti-bot behavior. Signed out it reads only public data; signed in, its experimental account tools read your own orders, cart, vouchers and notifications, and can change your cart, likes, follows and claimed vouchers — never checkout, payment, or account settings.

You are responsible for using this software in compliance with Shopee’s Terms of Service and applicable law. Use reasonable request volumes. All product names, logos, and brands are property of their respective owners.