Skillget

shopee-mcp

mcp
Security Audit
Warn
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 9 GitHub stars
Code Warn
  • fs module — File system access in package.json
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

MCP server for exploring Shopee product listings and prices, via an authenticated CloakBrowser session. Discovery only.

README.md

shopee-mcp

npm
license
CI
GitHub Repo

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.
check_login_status Whether the saved browser session is currently logged into Shopee — check this before the tools above instead of waiting on a slow failure.

Tool annotations

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

Tool Read-only Idempotent Destructive
search_products ✓ ✓ –
get_product_detail ✓ ✓ –
check_login_status ✓ ✓ –

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 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.
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.

Reviews (0)

No results found