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 | What it returns | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | search_products | Keyword search with sorting, filters (price range, min rating, seller location, Shopee Mall only) & pagination — prices, sold counts, IDs, URLs. | | get_product_detail | One product — price & discount, rating, sold count, stock, category, specs, shipping (fee, free-shipping threshold, ETA), seller, description. | | get_product_variants | Every variant of a listing — model IDs, variant names, per-variant prices and availability. Opt into includeStock for exact counts. | | get_product_reviews | Rating summary (star breakdown, with-media/comment counts) and pages of buyer reviews — filter by star rating, comments, or media. | | get_shop_info | A seller's profile by shop ID or username — badges, rating, products, followers, chat response rate/time, join date, last active. | | get_shop_products | One shop's catalogue, with sorting (popular, newest, top sales, price) & pagination. | | get_flash_sale | The current Flash Sale — session window, upcoming sessions, and deals with flash vs. original price and how much stock is claimed. | | check_login_status | Whether the saved browser session is logged into Shopee — check this first instead of waiting on a slow failure. |

Tool annotations

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

| Tool | Read-only | Idempotent | Destructive | | ---------------------- | :-------: | :--------: | :---------: | | search_products | ✓ | ✓ | – | | get_product_detail | ✓ | ✓ | – | | get_product_variants | ✓ | ✓ | – | | get_product_reviews | ✓ | ✓ | – | | get_shop_info | ✓ | ✓ | – | | get_shop_products | ✓ | ✓ | – | | get_flash_sale | ✓ | – | – | | check_login_status | ✓ | ✓ | – |

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

| Tool | What it returns | | ------------------- | -------------------------------------------------------------------------------------------------- | | get_orders | Your orders by tab (all, to ship, to receive, completed, cancelled) — status, shop, items, totals. | | get_order_detail | One order — items, total paid, payment channel, timeline, courier, tracking number & events. | | get_my_vouchers | Vouchers in your wallet — benefit, scope, minimum spend, expiry, code. | | get_coins | Shopee Coins balance and recent coin transactions. | | get_notifications | Order updates, promotions, or Shopee updates. | | get_cart | Your cart grouped by shop — items, variants, quantities, prices, model IDs. | | get_shop_vouchers | A shop's claimable vouchers, and which ones you've already claimed. |

Act on your account — these modify your Shopee account:

| Tool | What it does | | -------------------- | --------------------------------------------------------------------------- | | add_to_cart | Adds a product — the exact variant via modelId — in a quantity of 1-20. | | update_cart_item | Changes a cart line's quantity, or removes it with quantity: 0. | | like_product | Likes or unlikes a product. | | follow_shop | Follows or unfollows a shop. | | claim_shop_voucher | Claims one of a shop's vouchers into your wallet (a claim can't be undone). |

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.

| Variable | Default | Purpose | | ---------------------- | ------------------------------ | --------------------------------------------------------------- | | SHOPEE_DOMAIN | shopee.co.id | Regional Shopee domain (.co.id, .com.my, .sg, .tw). | | SHOPEE_LOCALE | derived from domain | Browser locale override. | | SHOPEE_TIMEZONE | derived from domain | Browser timezone override. | | SHOPEE_PROFILE_DIR | ~/.shopee-mcp/chrome-profile | Where the saved login lives. | | SHOPEE_HEADLESS | false | Keep false — headless is detected. | | SHOPEE_ACCOUNT_TOOLS | auto | auto: account tools while logged in. off: always read-only. | | CACHE_TTL_MS | 30000 | In-memory cache lifetime. | | DEBUG | false | Log startup/debug info to stderr. |

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

| Symptom | Likely cause / fix | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | 🔒 Not signed in / anonymous-request errors | No/expired session → run npm run login.