shopee-mcp

An MCP server for exploring Shopee — product search and prices — 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?). It performs no seller or account actions.

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

Tools

| Tool | What it returns | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | search_products | Keyword search with sorting & pagination — names, prices, sold counts, ratings, seller location, product IDs, URLs. | | get_product_detail | One product — price & discount, brand, condition, category, rating, review count, sold count, stock, location, description. |

Tool annotations

Per the MCP annotations spec — both tools are read-only, with no side effects.

| Tool | Read-only | Idempotent | Destructive | | -------------------- | :-------: | :--------: | :---------: | | search_products | ✓ | ✓ | – | | get_product_detail | ✓ | ✓ | – |

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. | | SHOPEE_PROFILE_DIR | ~/.shopee-mcp/chrome-profile | Where the saved login lives. | | SHOPEE_HEADLESS | false | Keep false — headless is detected. | | CACHE_TTL_MS | 30000 | In-memory cache lifetime. | | DEBUG | false | Log startup/debug info to stderr. |

Development

npm run lint         # eslint
npm run format       # prettier --write (format:check to verify)
npm run typecheck
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. | | error 90309999 or empty results | Shopee's anti-bot gate rejected the request. Ensure you're logged in and running headed (or via xvfb-run); retry. | | A read returns empty for a valid product | Shopee lazy-loads; retry, and run with DEBUG=true to inspect. | | Empty or stale results right after a change | In-memory cache — lower CACHE_TTL_MS or wait for the TTL to expire. | | Headless / server has no display | Wrap the command in xvfb-run -a …. |

Caveats

• Login required. No session → tools return 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.

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. It reads only publicly available product data and performs no account actions.

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.