{"_id":"@bintangtimurlangit/shopee-mcp","_rev":"4-f3324a67454508d4039c41e727457884","name":"@bintangtimurlangit/shopee-mcp","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@bintangtimurlangit/shopee-mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","shopee","indonesia","ecommerce","marketplace","product-search","discovery"],"license":"MIT","_id":"@bintangtimurlangit/shopee-mcp@0.1.0","maintainers":[{"name":"bintangtimurlangit","email":"btimurlangit@gmail.com"}],"homepage":"https://github.com/bintangtimurlangit/shopee-mcp#readme","bugs":{"url":"https://github.com/bintangtimurlangit/shopee-mcp/issues"},"bin":{"shopee-mcp":"build/index.js","shopee-mcp-login":"build/login.js"},"dist":{"shasum":"4b0ef8007a17c51ef129bacd25cfb96368a91386","tarball":"https://registry.npmjs.org/@bintangtimurlangit/shopee-mcp/-/shopee-mcp-0.1.0.tgz","fileCount":48,"integrity":"sha512-7AME0is4jk8HGT7P4M/4CTbA8Ly1YFNHXZAMvksmN46c8r+G5Wj+s+dR1RINwAda/sRlzqLOj6UzKD/hOsIx1g==","signatures":[{"sig":"MEQCICaNFmYDnhSMlNA0Orqw1FLJlSnD/fREtms6JI/X8h6ZAiAiQWcURMDxTaosUI15qXJBcRoG4ak1eidDgcpsefVqng==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":84565},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"da25b30fb0db9580349d8f7116488df0e78939cb","scripts":{"dev":"tsx watch src/index.ts","lint":"eslint .","test":"tsx test/smoke.ts","build":"tsc","clean":"node -e \"require('fs').rmSync('build',{recursive:true,force:true})\"","login":"tsx src/login.ts","start":"node build/index.js","format":"prettier --write .","prepare":"husky","lint:fix":"eslint . --fix","prebuild":"npm run clean","typecheck":"tsc --noEmit","format:check":"prettier --check .","prepublishOnly":"npm run build"},"_npmUser":{"name":"bintangtimurlangit","email":"btimurlangit@gmail.com"},"repository":{"url":"git+https://github.com/bintangtimurlangit/shopee-mcp.git","type":"git"},"_npmVersion":"11.16.0","description":"An MCP server for exploring Shopee — product search and prices via an authenticated browser session. Discovery only, no seller features.","directories":{},"lint-staged":{"*.ts":"eslint --fix","*.{ts,js,json,md,yml,yaml}":"prettier --write"},"_nodeVersion":"24.16.0","dependencies":{"zod":"^3.25.76","dotenv":"^17.4.2","playwright":"^1.49.0","cloakbrowser":"^0.4.10","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.0","husky":"^9.1.7","eslint":"^9.17.0","prettier":"^3.4.2","@eslint/js":"^9.17.0","typescript":"^5.9.0","@types/node":"^24.0.0","lint-staged":"^15.3.0","@commitlint/cli":"^19.6.1","typescript-eslint":"^8.19.0","eslint-config-prettier":"^9.1.0","@commitlint/config-conventional":"^19.6.0"},"_npmOperationalInternal":{"tmp":"tmp/shopee-mcp_0.1.0_1784396020906_0.06595959948053864","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@bintangtimurlangit/shopee-mcp","version":"0.1.1","keywords":["mcp","model-context-protocol","shopee","indonesia","ecommerce","marketplace","product-search","discovery"],"author":{"name":"bintangtimurlangit"},"license":"MIT","_id":"@bintangtimurlangit/shopee-mcp@0.1.1","maintainers":[{"name":"bintangtimurlangit","email":"btimurlangit@gmail.com"}],"homepage":"https://github.com/bintangtimurlangit/shopee-mcp#readme","bugs":{"url":"https://github.com/bintangtimurlangit/shopee-mcp/issues"},"bin":{"shopee-mcp":"build/index.js","shopee-mcp-login":"build/login.js"},"dist":{"shasum":"e480f1238f8e2b82e9bade208dddae94cd6adfc4","tarball":"https://registry.npmjs.org/@bintangtimurlangit/shopee-mcp/-/shopee-mcp-0.1.1.tgz","fileCount":48,"integrity":"sha512-pNpm2Gld95LFUHk2UW/qgPw34pLtIACXcyWOgNofgNz1Yjbf1y1Foz194WcMchwwzgNBiwGnEy5KYAL/yYR/WQ==","signatures":[{"sig":"MEUCIEVWg+EBy1FCLa52wSkh/lmgBzN3Jf8uzI1WyDQXDV1TAiEAhXLJAyqaH3JrBMIEt8n+qCdvPB9i37c9qFJLZMzW/uM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bintangtimurlangit%2fshopee-mcp@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":85342},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"f416b215009f4072ec32a1e8247f85cd1b4b67e9","scripts":{"dev":"tsx watch src/index.ts","lint":"eslint .","test":"tsx test/smoke.ts","build":"tsc","clean":"node -e \"require('fs').rmSync('build',{recursive:true,force:true})\"","login":"tsx src/login.ts","start":"node build/index.js","format":"prettier --write .","prepare":"husky","lint:fix":"eslint . --fix","prebuild":"npm run clean","typecheck":"tsc --noEmit","format:check":"prettier --check .","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:9276b34c-6d15-4cd2-9920-039e90ea3919"}},"repository":{"url":"git+https://github.com/bintangtimurlangit/shopee-mcp.git","type":"git"},"_npmVersion":"11.16.0","description":"An MCP server for exploring Shopee — product search and prices via an authenticated browser session. Discovery only, no seller features.","directories":{},"lint-staged":{"*.ts":"eslint --fix","*.{ts,js,json,md,yml,yaml}":"prettier --write"},"_nodeVersion":"24.18.0","dependencies":{"zod":"^3.25.76","dotenv":"^17.4.2","playwright":"^1.49.0","cloakbrowser":"^0.4.12","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.1","husky":"^9.1.7","eslint":"^10.7.0","prettier":"^3.4.2","@eslint/js":"^10.0.1","typescript":"^5.9.0","@types/node":"^24.0.0","lint-staged":"^17.1.0","@commitlint/cli":"^21.2.1","typescript-eslint":"^8.65.0","eslint-config-prettier":"^10.1.8","@commitlint/config-conventional":"^21.2.0"},"_npmOperationalInternal":{"tmp":"tmp/shopee-mcp_0.1.1_1784596046200_0.17334408358621212","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@bintangtimurlangit/shopee-mcp","version":"0.2.0","keywords":["mcp","model-context-protocol","shopee","indonesia","ecommerce","marketplace","product-search","discovery"],"author":{"name":"bintangtimurlangit"},"license":"MIT","_id":"@bintangtimurlangit/shopee-mcp@0.2.0","maintainers":[{"name":"bintangtimurlangit","email":"btimurlangit@gmail.com"}],"homepage":"https://github.com/bintangtimurlangit/shopee-mcp#readme","bugs":{"url":"https://github.com/bintangtimurlangit/shopee-mcp/issues"},"bin":{"shopee-mcp":"build/index.js","shopee-mcp-login":"build/login.js"},"dist":{"shasum":"10b30cee7fb745a4a9c28581421ee6f3c1897df9","tarball":"https://registry.npmjs.org/@bintangtimurlangit/shopee-mcp/-/shopee-mcp-0.2.0.tgz","fileCount":52,"integrity":"sha512-mOBTdZp+8f0O1G2/dTFEoJEp7TTdA0T4vrLGhdGScs0f115AVSp+eoKW4CS5Cv/yIb7lnNoOrWQ5/WT5kvMIrA==","signatures":[{"sig":"MEQCIFhu6M3zfcfWY+/bwl0ZSKlx2rztaHth3GCOeknuCX10AiB980kWG7E9sKHZQkP8kaUtELMZyLeZtj74AmnT2jzlpw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bintangtimurlangit%2fshopee-mcp@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":94257},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"81d285438e8bc5cf16a0609d9a6e2db11088eba2","scripts":{"dev":"tsx watch src/index.ts","lint":"eslint .","test":"tsx test/smoke.ts","build":"tsc","clean":"node -e \"require('fs').rmSync('build',{recursive:true,force:true})\"","login":"tsx src/login.ts","start":"node build/index.js","format":"prettier --write .","prepare":"husky","lint:fix":"eslint . --fix","prebuild":"npm run clean","test:unit":"tsx test/unit.ts","typecheck":"tsc --noEmit","format:check":"prettier --check .","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:9276b34c-6d15-4cd2-9920-039e90ea3919"}},"repository":{"url":"git+https://github.com/bintangtimurlangit/shopee-mcp.git","type":"git"},"_npmVersion":"11.16.0","description":"An MCP server for exploring Shopee — product search and prices via an authenticated browser session. Discovery only, no seller features.","directories":{},"lint-staged":{"*.ts":"eslint --fix","*.{ts,js,json,md,yml,yaml}":"prettier --write"},"_nodeVersion":"24.18.0","dependencies":{"zod":"^3.25.76","dotenv":"^17.4.2","playwright":"^1.49.0","cloakbrowser":"^0.5.5","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.1","husky":"^9.1.7","eslint":"^10.7.0","prettier":"^3.4.2","@eslint/js":"^10.0.1","typescript":"^5.9.0","@types/node":"^24.0.0","lint-staged":"^17.1.0","@commitlint/cli":"^21.2.1","typescript-eslint":"^8.65.0","eslint-config-prettier":"^10.1.8","@commitlint/config-conventional":"^21.2.0"},"_npmOperationalInternal":{"tmp":"tmp/shopee-mcp_0.2.0_1786518385372_0.5601786290706845","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"_id":"@bintangtimurlangit/shopee-mcp@0.3.0","bin":{"shopee-mcp":"build/index.js","shopee-mcp-login":"build/login.js"},"bugs":{"url":"https://github.com/bintangtimurlangit/shopee-mcp/issues"},"dist":{"shasum":"b246e8a32ae2e069a2d1247f3ce4fd141219ce1c","tarball":"https://registry.npmjs.org/@bintangtimurlangit/shopee-mcp/-/shopee-mcp-0.3.0.tgz","fileCount":88,"integrity":"sha512-osCRB9xaM+3/jXcvyqzlh+IWXq8XFD5wSRk9ZW0DO4YjjtEm24BXPX53OGRdg9xABGvlH8BeDA/zHvdyJxxEkQ==","signatures":[{"sig":"MEQCIBvTQByawZfK1svTXsQDre8XSFHRGljse7JTu2h9YWa5AiAwUUgQ/hdLGIZaazHrxuNyXdSkDLlaoaANTZ3nkiTzKQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBVpoRwTj9n4ePCitK06qfsow0p27Xnn5cRRFc8KzbGLAiEAotmazs/8s42gg9ILUYgkEfX/N/WC3Z2kyQozokZji4c="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bintangtimurlangit%2fshopee-mcp@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":339317},"name":"@bintangtimurlangit/shopee-mcp","type":"module","author":{"name":"bintangtimurlangit"},"engines":{"node":">=18.0.0"},"gitHead":"8f14b96c6b095d60a88b40471c6e7bafd4f96ec0","license":"MIT","scripts":{"dev":"tsx watch src/index.ts","lint":"eslint .","test":"tsx test/smoke.ts","build":"tsc","clean":"node -e \"require('fs').rmSync('build',{recursive:true,force:true})\"","login":"tsx src/login.ts","start":"node build/index.js","format":"prettier --write .","prepare":"husky","lint:fix":"eslint . --fix","prebuild":"npm run clean","test:unit":"tsx test/unit.ts","typecheck":"tsc --noEmit","format:check":"prettier --check .","prepublishOnly":"npm run build"},"version":"0.3.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"9276b34c-6d15-4cd2-9920-039e90ea3919"}},"homepage":"https://github.com/bintangtimurlangit/shopee-mcp#readme","keywords":["mcp","model-context-protocol","shopee","indonesia","ecommerce","marketplace","product-search","discovery"],"repository":{"url":"git+https://github.com/bintangtimurlangit/shopee-mcp.git","type":"git"},"_npmVersion":"11.19.0","description":"An MCP server for exploring Shopee — product search and prices via an authenticated browser session. Discovery only, no seller features.","directories":{},"lint-staged":{"*.ts":"eslint --fix","*.{ts,js,json,md,yml,yaml}":"prettier --write"},"maintainers":[{"name":"bintangtimurlangit","email":"btimurlangit@gmail.com"}],"_nodeVersion":"24.21.0","dependencies":{"zod":"^3.25.76","dotenv":"^17.4.2","playwright":"^1.49.0","cloakbrowser":"^0.5.5","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.1","husky":"^9.1.7","eslint":"^10.7.0","prettier":"^3.4.2","@eslint/js":"^10.0.1","typescript":"^5.9.0","@types/node":"^24.0.0","lint-staged":"^17.1.0","@commitlint/cli":"^21.2.1","typescript-eslint":"^8.65.0","eslint-config-prettier":"^10.1.8","@commitlint/config-conventional":"^21.2.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/shopee-mcp_0.3.0_1790689071706_0.028479862806707334"}}},"time":{"created":"2026-07-18T17:33:40.673Z","modified":"2026-09-29T13:37:52.408Z","0.1.0":"2026-07-18T17:33:41.069Z","0.1.1":"2026-07-21T01:07:26.321Z","0.2.0":"2026-08-12T07:06:25.504Z","0.3.0":"2026-09-29T13:37:51.829Z"},"bugs":{"url":"https://github.com/bintangtimurlangit/shopee-mcp/issues"},"author":{"name":"bintangtimurlangit"},"license":"MIT","homepage":"https://github.com/bintangtimurlangit/shopee-mcp#readme","keywords":["mcp","model-context-protocol","shopee","indonesia","ecommerce","marketplace","product-search","discovery"],"repository":{"url":"git+https://github.com/bintangtimurlangit/shopee-mcp.git","type":"git"},"description":"An MCP server for exploring Shopee — product search and prices via an authenticated browser session. Discovery only, no seller features.","maintainers":[{"name":"bintangtimurlangit","email":"btimurlangit@gmail.com"}],"readme":"# shopee-mcp\n\n[![npm](https://img.shields.io/npm/v/@bintangtimurlangit/shopee-mcp?style=flat-square)](https://www.npmjs.com/package/@bintangtimurlangit/shopee-mcp)\n[![license](https://img.shields.io/github/license/bintangtimurlangit/shopee-mcp?style=flat-square)](./LICENSE)\n[![CI](https://img.shields.io/github/actions/workflow/status/bintangtimurlangit/shopee-mcp/ci.yml?branch=main&style=flat-square)](https://github.com/bintangtimurlangit/shopee-mcp/actions)\n[![GitHub Repo](https://img.shields.io/badge/GitHub-shopee--mcp-24292f?style=flat-square&logo=github)](https://github.com/bintangtimurlangit/shopee-mcp)\n\nAn 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.\n\n> **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?](#why-a-browser)). Signed out it is read-only; signed in it also offers [experimental account tools](#account-mode-experimental) for your orders, cart, vouchers, likes and follows.\n\n**Full reference:** [Documentation](./docs/README.md) · **Changelog:** [CHANGELOG.md](./CHANGELOG.md) · **Versioning & releases:** [docs/RELEASES.md](./docs/RELEASES.md)\n\n## Tools\n\n| Tool                   | What it returns                                                                                                                                            |\n| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `search_products`      | Keyword search with sorting, **filters** (price range, min rating, seller location, Shopee Mall only) & pagination — prices, sold counts, IDs, URLs.       |\n| `get_product_detail`   | One product — price & discount, rating, sold count, stock, category, **specs**, **shipping** (fee, free-shipping threshold, ETA), **seller**, description. |\n| `get_product_variants` | Every variant of a listing — model IDs, variant names, per-variant prices and availability. Opt into `includeStock` for exact counts.                      |\n| `get_product_reviews`  | Rating summary (star breakdown, with-media/comment counts) and pages of buyer reviews — filter by star rating, comments, or media.                         |\n| `get_shop_info`        | A seller's profile by shop ID or username — badges, rating, products, followers, chat response rate/time, join date, last active.                          |\n| `get_shop_products`    | One shop's catalogue, with sorting (popular, newest, top sales, price) & pagination.                                                                       |\n| `get_flash_sale`       | The current Flash Sale — session window, upcoming sessions, and deals with flash vs. original price and how much stock is claimed.                         |\n| `check_login_status`   | Whether the saved browser session is logged into Shopee — check this first instead of waiting on a slow failure.                                           |\n\n### Tool annotations\n\nPer the [MCP annotations spec](https://modelcontextprotocol.io/) — every default tool is read-only, with no side effects.\n\n| Tool                   | Read-only | Idempotent | Destructive |\n| ---------------------- | :-------: | :--------: | :---------: |\n| `search_products`      |     ✓     |     ✓      |      –      |\n| `get_product_detail`   |     ✓     |     ✓      |      –      |\n| `get_product_variants` |     ✓     |     ✓      |      –      |\n| `get_product_reviews`  |     ✓     |     ✓      |      –      |\n| `get_shop_info`        |     ✓     |     ✓      |      –      |\n| `get_shop_products`    |     ✓     |     ✓      |      –      |\n| `get_flash_sale`       |     ✓     |     –      |      –      |\n| `check_login_status`   |     ✓     |     ✓      |      –      |\n\n## Account mode (experimental)\n\nWhen 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.\n\n**Read your account**\n\n| Tool                | What it returns                                                                                    |\n| ------------------- | -------------------------------------------------------------------------------------------------- |\n| `get_orders`        | Your orders by tab (all, to ship, to receive, completed, cancelled) — status, shop, items, totals. |\n| `get_order_detail`  | One order — items, total paid, payment channel, timeline, courier, tracking number & events.       |\n| `get_my_vouchers`   | Vouchers in your wallet — benefit, scope, minimum spend, expiry, code.                             |\n| `get_coins`         | Shopee Coins balance and recent coin transactions.                                                 |\n| `get_notifications` | Order updates, promotions, or Shopee updates.                                                      |\n| `get_cart`          | Your cart grouped by shop — items, variants, quantities, prices, model IDs.                        |\n| `get_shop_vouchers` | A shop's claimable vouchers, and which ones you've already claimed.                                |\n\n**Act on your account** — these modify your Shopee account:\n\n| Tool                 | What it does                                                                |\n| -------------------- | --------------------------------------------------------------------------- |\n| `add_to_cart`        | Adds a product — the exact variant via `modelId` — in a quantity of 1-20.   |\n| `update_cart_item`   | Changes a cart line's quantity, or removes it with `quantity: 0`.           |\n| `like_product`       | Likes or unlikes a product.                                                 |\n| `follow_shop`        | Follows or unfollows a shop.                                                |\n| `claim_shop_voucher` | Claims one of a shop's vouchers into your wallet (a claim can't be undone). |\n\nHow they stay safe:\n\n- **Nothing checks out, pays, or touches addresses, payment methods, passwords, or chat.** Order detail omits your address and phone number.\n- Every action clicks **Shopee's own button** on the real page (never a hand-crafted request), then reports only what Shopee's response confirmed.\n- They check the current state first — liking a liked product, or claiming a claimed voucher, changes nothing.\n- 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.\n\nThey drive Shopee's UI, so a site redesign can break them — hence _experimental_. The cart tools build on [@DystopiaOwO](https://github.com/DystopiaOwO)'s fork.\n\n## Why a browser?\n\nShopee 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.\n\nSo this server:\n\n1. Drives **[CloakBrowser](https://github.com/CloakHQ/cloakbrowser)** — a Chromium with binary-level fingerprint patches — against a **persistent profile you log into once**.\n2. **Navigates to the real Shopee page and intercepts the response** its own app fetches, so the request carries valid signatures.\n\nThe browser must run **headed** (Shopee detects headless); on a server use a virtual display (`xvfb`).\n\n### From npm (recommended)\n\n```bash\nnpm install -g @bintangtimurlangit/shopee-mcp   # downloads the CloakBrowser binary (~200 MB, cached)\n```\n\nThis 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`.\n\n### From source\n\n```bash\ngit clone https://github.com/bintangtimurlangit/shopee-mcp.git\ncd shopee-mcp\nnpm install          # also downloads the CloakBrowser binary (~200 MB, cached)\nnpm run build\n```\n\n### 1. Log in once\n\nShopee blocks anonymous requests, so you sign in one time. This saves a session to `~/.shopee-mcp/chrome-profile`.\n\n```bash\nshopee-mcp-login     # global install — or, from a source checkout:  npm run login\n```\n\n- Opens a CloakBrowser window — log in, then press Enter.\n- On a desktop / WSLg, the window appears normally.\n- Re-run only when the session expires.\n\n### 2. Register with your MCP client\n\nThe server launches a **headed** browser, so it needs a display. On a headless machine, wrap it with `xvfb-run`.\n\nClaude Desktop / Claude Code `mcpServers` entry:\n\n```json\n{\n  \"mcpServers\": {\n    \"shopee\": {\n      \"command\": \"xvfb-run\",\n      \"args\": [\"-a\", \"shopee-mcp\"]\n    }\n  }\n}\n```\n\nOn 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).\n\n## Configuration\n\nAll optional — see `.env.example`. Copy to `.env` to override.\n\n| Variable               | Default                        | Purpose                                                         |\n| ---------------------- | ------------------------------ | --------------------------------------------------------------- |\n| `SHOPEE_DOMAIN`        | `shopee.co.id`                 | Regional Shopee domain (`.co.id`, `.com.my`, `.sg`, `.tw`).     |\n| `SHOPEE_LOCALE`        | _derived from domain_          | Browser locale override.                                        |\n| `SHOPEE_TIMEZONE`      | _derived from domain_          | Browser timezone override.                                      |\n| `SHOPEE_PROFILE_DIR`   | `~/.shopee-mcp/chrome-profile` | Where the saved login lives.                                    |\n| `SHOPEE_HEADLESS`      | `false`                        | Keep `false` — headless is detected.                            |\n| `SHOPEE_ACCOUNT_TOOLS` | `auto`                         | `auto`: account tools while logged in. `off`: always read-only. |\n| `CACHE_TTL_MS`         | `30000`                        | In-memory cache lifetime.                                       |\n| `DEBUG`                | `false`                        | Log startup/debug info to stderr.                               |\n\nTool timings and client timeouts: see [docs/CONFIGURATION.md](./docs/CONFIGURATION.md#tools-and-request-timeouts).\n\n## Development\n\n```bash\nnpm run lint         # eslint\nnpm run format       # prettier --write (format:check to verify)\nnpm run typecheck\nnpm run test:unit    # offline unit tests (no login/display needed)\nnpm test             # live smoke test (needs a display; use xvfb-run on servers)\nnpm run dev          # tsx watch\n```\n\nMore detail: **[docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md)**.\n\n## Troubleshooting\n\n| Symptom                                       | Likely cause / fix                                                                                                      |\n| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `🔒 Not signed in` / anonymous-request errors | No/expired session → run `npm run login`.                                                                               |\n| `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. |\n| A read returns empty for a valid product      | Shopee lazy-loads; retry, and run with `DEBUG=true` to inspect.                                                         |\n| Empty or stale results right after a change   | In-memory cache — lower `CACHE_TTL_MS` or wait for the TTL to expire.                                                   |\n| Headless / server has no display              | Wrap the command in `xvfb-run -a …`.                                                                                    |\n\n## Caveats\n\n- **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.\n- **Anti-bot is a moving target.** The free CloakBrowser binary can go stale as Shopee updates detection; CloakBrowser Pro ships newer patches.\n- Respect Shopee's Terms of Service. This is for personal market exploration, not scraping at scale.\n- **Regions.** Indonesia is the most tested; Malaysia, Singapore and Taiwan get the matching locale, timezone and currency automatically.\n\n## Contributing & security\n\n[CONTRIBUTING.md](./CONTRIBUTING.md) · [SECURITY.md](./SECURITY.md) · [Code of Conduct](./CODE_OF_CONDUCT.md)\n\n## License\n\n[MIT](./LICENSE)\n\n---\n\n## Disclaimer\n\nThis is an **unofficial** project. It is **not affiliated with, authorized, maintained, sponsored, or endorsed by Shopee or Sea Limited**.\n\nIt 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.\n\nYou are responsible for using this software in compliance with [Shopee's Terms of Service](https://shopee.co.id/docs/terms) and applicable law. Use reasonable request volumes. All product names, logos, and brands are property of their respective owners.\n","readmeFilename":"README.md"}