🛒 Quick Commerce MCP

Universal quick commerce aggregation via MCP - compare and order from Zepto, Blinkit, and Swiggy Instamart in one interface.

Current verification scope: Blinkit and Zepto search/cart flows were checked for 1.5.1. Checkout, payments, and order tracking were not reverified; Instamart was not included in this regression check. See flow status before relying on a feature.

✨ Features

• Multi-Platform Search: Find products across all platforms simultaneously

• Price Comparison: See which app has the best deal

• Smart Cart: Automatically suggest optimal platform split

• Item Resolution: resolve_items ranks matches per platform; add_to_cart validates the cart (items, quantities, bill total) after adding

• Itemised Bill: Handling, late-night, GST and other fees listed separately in cart and order preview

• Addresses: list_addresses / select_address (retries once on flaky picker clicks)

• Store Notices: Closed/unserviceable stores and "Add address to proceed" are detected and reported with next steps

• User Control (not reverified): Two-step place_order (preview token, then confirm); CVV read from QC_CVV_<last4>, never logged

• Payment QR (not reverified): Zepto UPI QR support is implemented, including full-resolution cropping and an optional image viewer; successful payment is not guaranteed by generating a QR

• OTP Handling: Prompts for OTP when session expires

Related MCP server: comparebasket

Demo

🚀 Quick Start

Requirements: Node 18+ and Google Chrome installed (the server drives your Chrome, no browser download). It runs locally over stdio, so it works in local MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf), not hosted web apps.

1. Add the server to your MCP client. No install step; npx fetches it.

Claude Code:

claude mcp add quick-commerce -- npx -y quick-commerce-mcp

Claude Desktop, Cursor, Windsurf (add to the client's MCP config, then restart it):

{
  "mcpServers": {
    "quick-commerce": {
      "command": "npx",
      "args": ["-y", "quick-commerce-mcp"]
    }
  }
}

2. Set up from chat. Ask your assistant, for example: "Save my phone 98XXXXXXXX and UPI me@bank, then log me in to Blinkit."

The verified shopping path for Blinkit and Zepto is search_products → add_to_cart → get_cart_summary → remove_from_cart / clear_cart. compare_prices and resolve_items have shared logic test coverage, but their full multi-platform flow was not reverified. Checkout via get_order_preview / place_order remains outside this verified shopping path. Blinkit history and latest-order lookup were live verified separately on 2026-10-18; see flow status.

Always pass payment_method explicitly to place_order. Your saved default is a single value applied to every platform, and the same string means different things on different ones — upi is Blinkit-only, and Zepto needs upi_qr for a scannable QR. Relying on the default is the most common reason a payment method comes back unsupported.

Alternative login from a terminal (opens a browser; log in, then Ctrl+C):

npx -y -p quick-commerce-mcp quick-commerce-mcp-login zepto   # also: blinkit, swiggy-instamart

Sessions are saved to ~/.quick-commerce-mcp/sessions/ and expire eventually; just log in again.

3. Optional, for card payments: export QC_CVV_<last4> in the client's env block. UPI needs no secret.

From source: npm install && npm run build, then point the client at node /path/to/dist/index.js.

Tests: install the test browser with npx playwright install chromium, then run npm test and npm run lint. To use an existing Chromium executable, set QC_CHROME_PATH when running the tests. The browser regression tests use local fixture storefronts; they do not use saved sessions or make live purchases.

Supported platforms and flow status

Status for 1.5.1, checked 2026-10-04. Release verification ran 64 automated tests plus live Blinkit/Zepto checks against the packaged build. This is the scope of those checks, not a guarantee that every product, address, store, or future site update will behave identically.

• Live verified: exercised against the real platform during this release check.

• Test covered: exercised by unit tests or controlled browser fixtures, not a dedicated live check of that scenario.

• Not reverified: implemented or previously reported working, but not checked in this release. This does not mean it is known broken.

• Unsupported / previously failed: an explicit implementation gap or a prior failure; a prior failure is not a fresh result for this release.

Purchase history (Blinkit, Zepto and BigBasket)

Use get_order_history to list ordered items and their historical prices for a date range. For example:

{
  "platform": "blinkit",
  "start_date": "2026-10-01",
  "end_date": "2026-10-31",
  "max_orders": 100
}

Dates are inclusive purchase dates in Asia/Kolkata, verified from merchant order timestamps or dated order details, including the year. Recent today/yesterday labels resolve against the response time in Asia/Kolkata. Active-order tracking links are supported too. Each order includes status, item name, pack size, quantity, charged lineTotal, derived unitPrice, item subtotal, fees and bill total. A pack such as 4 x 750 ml remains one product pack; ordered quantity is separate. Discounted prices exclude crossed-out MRP. Item amounts must reconcile with the bill.

All three adapters navigate normal account pages and read the browser responses. Zepto converts the merchant's paise amounts to rupees, combines its separate item and bill page responses, and follows Load More. BigBasket flattens grouped shipments and keeps active/recent/past pagination separate from any date-boundary assumption. Blinkit and Zepto can stop after crossing a verified newest-first purchase-date boundary; BigBasket exhausts its grouped history. complete: false with warnings means orders could not be read/reconciled, pagination did not progress, or an inspection limit was reached. Do not describe such output as all orders. max_orders limits orders inspected (including orders outside the range), defaults to 100 and accepts 1–200. Large scans may need a longer MCP client timeout. The tool never reorders, changes the cart or submits payment, and omits addresses and payment details.

Verified on 2026-10-18 through a fresh local stdio MCP process against the saved Blinkit session. A running MCP process must reconnect after rebuilding to discover changes to the tool schema. Set platform to blinkit, zepto or bigbasket. Swiggy Instamart date-range history is not implemented.

Zepto and BigBasket development support is live verified through a fresh local stdio MCP process: Zepto followed multiple history pages; BigBasket read the available cancelled order through the existing Windows background-browser bridge. BigBasket pagination beyond its available single page is fixture-tested. Its native Linux browser failed in this environment; start the documented scripts/bigbasket-windows-bridge.mjs from WSL and keep it running to share the dedicated browser with MCP. No session or OTP is copied to an unrelated browser.

Cancelled/refunded orders retain their status and historical bill values; those values are not spending totals. BigBasket returns total before wallet and NeuCoins credits, credits separately, and amountPayable after those credits. refundTotal is exposed when the merchant provides it. Historical item quantities count ordered packs; BigBasket also reports fulfilledQuantity when available. Item, bill, credit and refund parsing is fixture-tested, including waived charges, discounts, wrong order identity, missing rows, scan limits and incomplete pagination.

BigBasket development support (2026-10-04)

The working tree adds bigbasket to the MCP tools and interactive login helper. It supports OTP login, search, ID-based cart additions with basket quantity verification, individual removal, saved-address selection, and checkout preview. Payment options are read from the Juspay iframe, and the preview reads the actual payable total, including checkout discounts. Eligible wallet execution uses the shared wallet controller. UPI QR generation uses a confirmed, one-shot handoff; other payment execution and bulk clearing remain disabled. Checkout stops if BigBasket requests removal of unavailable pre-existing items; it does not confirm that removal automatically.

After login, the connector reuses a confirmed address saved per platform. A pincode selects a saved address only when the match is unique. Otherwise, the login response lists the available saved addresses and asks the user to choose with select_address; that confirmed choice persists across restarts. If a saved choice disappears, the connector asks again instead of substituting another home.

Live stdio MCP verification completed OTP login in a dedicated native Windows Chromium browser, reused the saved Bangalore Home address, increased an existing biscuits item from one to two packs, and confirmed the persisted quantity by reloading the basket. The original one-pack quantity was then restored. Checkout preview returned the delivery address, payment options and actual payable total of ₹133.94 (items ₹126.50, handling ₹8, checkout discount ₹0.56). No payment or order was submitted. Live prepare_payment opened the UPI category through its Juspay article[role=none] control without submitting anything. Collect/QR transaction generation and authorization remain untested. Reconnecting a fresh MCP process reused the authenticated browser and confirmed address without another OTP. Full browser restart login restoration has not been verified live.

BigBasket's full listing service and product detail pages still return access refusals in the authenticated native browser. New-product search and additions now work through the supported storefront autocomplete UI: the adapter waits for the rendered search input, uses the last visible input (the sticky header), reads native suggestions and clicks their Add controls. It reports that these are limited suggestions, not exhaustive catalog results. Refine the query when a desired product is absent. The full listing remains a fallback when suggestions are unavailable; a refusal is reported without requesting another OTP.

Live fresh stdio MCP verification searched Marie, returned ten variants, added one Britannia Marie Gold Biscuits 190 g pack (ID 40001610, ₹28.65), and reloaded the basket to prove it persisted beside the existing biscuits. The two-item subtotal was ₹155.15. No payment or order was submitted. Search state is restored after cart reads; new-product Add dispatches once and requires basket proof before any subsequent quantity increment. Missing optional images never cause a locator timeout. Fixtures cover autocomplete restoration, rejected writes, restored basket IDs, unavailable-item protection, checkout authentication, address extraction, iframe options and actual totals.

Actual MCP verification on 2026-10-04 also found that the already-connected server was stale: it returned Platform bigbasket not supported, while a fresh stdio connection to dist/index.js registered all 16 BigBasket tools. Restart the MCP connection after building; rebuilding files does not update a running Node process. scripts/verify-bigbasket-mcp.mjs exercises that fresh stdio connection (newline-delimited tool requests on stdin, quit to close).

BigBasket uses native desktop browser APIs. Direct MCP launch now defaults to headless (QC_BIGBASKET_HEADLESS=false explicitly enables visible recovery). Live Windows and WSL headless tests on 2026-10-04 were rejected by the storefront; changing the headless user-agent did not fix this. Login cookies remained valid in the normal Windows browser. No new OTP or payment was sent during those tests.

The Windows bridge defaults to background mode: ordinary Chrome runs on a private Windows desktop that is never switched into view. This is an invisible local workaround, not true headless and not a cloud/Linux solution. The launcher checks that Chrome created its window on that private desktop before reporting ready. Live MCP checks verified saved login/address, native search, cart contents, and checkout/payment options, including after reconnect/restart. The MCP process, project, preferences and session files remain in WSL:

# From WSL, install the Windows browser runtime into the Windows user's home.
WINDOWS_HOME=$(wslpath -u "$(cmd.exe /d /c echo %USERPROFILE% | tr -d '\r')")
PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=win64 \
  PLAYWRIGHT_BROWSERS_PATH="$WINDOWS_HOME/.quick-commerce-mcp/browser-runtime" \
  npx playwright install chromium
node scripts/bigbasket-windows-bridge.mjs
# Explicit recovery or headless experiments:
QC_BIGBASKET_BROWSER_MODE=visible node scripts/bigbasket-windows-bridge.mjs
QC_BIGBASKET_BROWSER_MODE=headless node scripts/bigbasket-windows-bridge.mjs

Stop the existing bridge before changing modes; one dedicated profile must not have competing browser owners. Keep the bridge running while using MCP. It publishes an owner-only loopback endpoint registry for automatic attachment and never logs CDP frames or credentials. Optional QC_WINDOWS_NODE_PATH and QC_WINDOWS_BROWSER_PATH specify WSL paths to Windows runtime executables; the default Node runtime comes from the Codex desktop dependency cache. An explicit QC_BIGBASKET_CDP_URL must be a plain loopback HTTP origin. This remains a development helper, not a bundled npm installation feature. Claude's local MCP connection can attach to it; remote clients cannot attach to your loopback browser. Payment dispatch/redirects and fresh OTP login have not been verified in background mode. Switch explicitly to visible recovery when the site requires human interaction. MCP disconnect preserves the browser; logout clears its cookies, origin storage and cached authenticated pages. Session files use owner-only permissions. Rebuilding does not refresh an existing MCP process.

Payment routing and user preferences (development)

All four apps share get_payment_options, prepare_payment, and set_payment_preferences. The default order is UPI collect, UPI QR, wallets, cards, then COD. A checkout advertising only “UPI” must be inspected to determine its actual modes; it does not prove collect or QR support. Disabled methods are excluded. Missing UPI IDs, wallet providers, or saved-card choices are requested before proceeding. Optional netbanking, Pay Later, and Pluxee options can also be included in a custom order when advertised by the website.

Examples:

{"order":["upi","wallet","card","cod"],"allow_fallback":true}
{"platform":"bigbasket","order":["wallet","upi_qr","cod"],"wallet_provider":"Amazon Pay"}
{"platform":"blinkit","order":["upi_collect"],"upi_id":"person@bank","allow_fallback":false}
{"platform":"zepto","order":["card","upi_qr"],"card_last4":"1234"}

Pass these to set_payment_preferences. Omitted methods are excluded from the priority order. Per-app fields inherit global fields; reset:true removes that scope. Preferences persist across restarts. Full card numbers, CVV, bank credentials and payment OTPs are never stored in these preferences.

get_payment_options returns option IDs, observed availability, prerequisites, a preferred option, and whether submission has an adapter or needs manual completion. prepare_payment opens a unique safe category tab, heading or recognized category button and inspects sub-options. It does not click final payment/provider buttons, initiate a collect request, generate a transaction QR, debit wallets, authorize cards or place orders. Ambiguous/unknown controls require choosing in the app. Website capabilities determine the available flow; app-only options are not fabricated.

Existing automated submission coverage remains:

place_order accepts auto or an omitted method for preference routing, but only adapter-supported modes can submit. Explicit order approval remains required; confirmation binds the same platform, method and UPI/card details. No fallback or retry occurs after submission, failure, timeout or an uncertain payment outcome. Resolve pending status or ask the user before another attempt. New routing/preparation is covered by browser fixtures and fresh stdio MCP integration tests. Live payment submission tests remain pending. BigBasket's MCP login, existing-cart updates and checkout are verified via the Windows browser bridge. Full listing-service search remains blocked; native autocomplete search and new-product addition are verified through fresh stdio MCP. Live read-only MCP verification reached Instamart's payment screen and returned UPI, wallet, card, netbanking and pay-on-delivery options at the saved Bangalore address. Zepto and Blinkit returned checkout-unavailable for their current sessions/carts. None of these checks submitted a payment or order.

Wallet execution depends on the actual checkout UI. get_wallet_status opens the safe Wallets category and lists native/linked provider balances and bill coverage. App credit (bbWallet, Zepto Cash, Swiggy Money, Blinkit wallet) and linked wallets such as Amazon Pay or MobiKwik use the shared controller when a unique balance and checkbox/radio are visible. Provider-only buttons, missing balances and linking/login requirements remain manual.

Use place_order(payment_method: "wallet", wallet_provider: "bbWallet", ...) for the normal two-step approval flow. Preparation spends nothing. Confirmation rechecks cart items, address, total, wallet identity and available balance; balance equal to the bill is sufficient. Applied wallet credit and zero residual payable must be observable before a separate final click. Linked-provider selection can itself initiate payment and is tracked as a possible dispatch. Authentication/pending/timeout outcomes never trigger retry, top-up, split payment or fallback. Success requires a new order confirmation and order ID; a click or balance change alone is insufficient.

Pending wallet attempts are recorded privately beside the platform session and block another attempt across MCP restarts. An exclusively created .pending marker guards overlapping processes. Reconcile unresolved attempts against order history before an operator removes their pending journal/marker; logout does not clear this protection.

Browser fixtures cover wallet success/failure on all four apps, linked balances and provider authentication. Actual wallet debits remain untested. Live BigBasket MCP inspection found bbWallet ₹0 against a ₹133.94 bill and PayZapp without a usable linked balance/control. Both were refused for automatic payment. No real order or wallet debit was submitted.

Instamart development verification (2026-10-04)

The working-tree Instamart adapter now restores searches for ID-only adds after cart navigation, includes pack size in product IDs, rejects ambiguous pack matches, detects out-of-stock items, and proves quantity changes against both the counter and completed cart writes. Removed rows showing ADD are excluded from the cart. OTP submission waits for authenticated state before saving, and checkout preview distinguishes Select Address from Proceed to Pay.

These changes have 13 browser fixture regressions in src/instamart-flows.test.ts, covering inline and variant adds, repeat adds, delayed/debounced saves, removal, clearing, rejected writes, session restoration, and checkout preview. This extends the working tree's coverage; the 1.5.1 release table above remains historical.

Live checks restored the saved session, returned 20 search results, read the cart, and removed a test item while preserving the original cart. Full live quantity/repeat-add verification was blocked by Instamart's HTTP-200 application error User Addresses not found for user. The adapter now reports that as a failure with list_addresses / select_address recovery. Select a valid delivery address before rerunning the live cart regression; successful full live parity has not been established. Payments and order history remain outside these checks.

Run npx tsx scripts/test-instamart-addtocart.ts for the live cart regression after configuring the address. It asserts outcomes and restores the original cart rather than clearing pre-existing items. QC_INSTAMART_TEST_QUERY can override the default test search (amul milk).

Known limitations and recovery

• Payments were deliberately excluded from the 1.5.1 regression checks. Older Blinkit UPI and Zepto QR demonstrations do not establish current reliability. Do not treat a QR or a returned success message as proof of payment or a confirmed order; check the platform's own app/order history.

• Instamart checkout preview previously failed, and this release did not retest that failure. Instamart order-status retrieval is not implemented. Its older search/cart results have not been reverified either.

• Configured payment modes are not a live verification promise: Blinkit accepts cod/upi/card, Zepto cod/upi_qr/card, and Instamart cod. The working tree also supports eligible native and linked wallet checkout on Blinkit, Zepto, Instamart and BigBasket through the shared wallet controller. Real wallet debits remain untested. New cards, netbanking and Pay Later remain manual; platform eligibility can disable a method for a particular cart.

• Older incomplete Blinkit sessions need one fresh OTP login. Version 1.5.1 waits for authenticated client state before saving; a leftover legacy cookie alone no longer counts as a logged-in account.

• Cart actions require confirmation where prompted. Repeat adds are treated as already present, not as instructions to add the requested quantity again. After removal/clearing, read get_cart_summary to confirm the result. Live verification used only test items and restored both carts to empty.

• Stock, store hours, and address eligibility remain platform-controlled. A closed/unserviceable notice is not a promise that checkout can proceed. Browser markup and bot checks can change; inspect a broken flow with diagnose_flow rather than assuming an earlier verification still applies.

The automated browser regressions are in src/platform-flows.test.ts; shared logic tests are in src/logic.test.ts. They use fixtures, not live accounts or purchases. Passing them does not certify checkout or payment flows.

See AUTHENTICATION.md for login troubleshooting - rejected OTPs, missing delivery locations, and how to log in by hand when the automated flow won't cooperate.

📝 Usage Examples

Search for a product

"Find Coke Zero 6-pack"
"Where is milk cheapest right now?"
"Search for Maggi noodles on Zepto and Swiggy"

Build a cart

"Add to cart: 1L milk, 6 eggs, bread"
"Show me the best platform for these items"

Compare before ordering

"Compare prices for my cart"
"What's the cheapest way to get these items?"

Pay by UPI QR

This feature is implemented but not reverified for 1.5.1. The example describes the intended flow, not a guarantee of payment success.

"Pay for my Zepto cart with a UPI QR"

The first call previews the order and stops. The second generates the QR, which is valid for a few minutes. It comes back cropped to the QR itself at full resolution, and the file path is always included. Run set_preferences(open_qr: "true") once to have it open in an image viewer automatically — see below for why that is worth turning on.

Zepto only: pass payment_method: "upi_qr" explicitly. Your saved default is used for every platform, and upi means something different on Blinkit than it does on Zepto.

🔐 Security

• No card data stored: CVV is read from the QC_CVV_<last4> env var only, and is never written anywhere. What is written locally, all under ~/.quick-commerce-mcp/: preferences.json (phone, pincode, UPI ID, default payment method, open_qr), session cookies in sessions/, repaired selectors in flows/, and payment QR images in sessions/

• A payment QR is saved to disk: a UPI QR is a scannable payment instruction — it carries the payee VPA, the amount and a transaction reference. It is written to sessions/ so you can open it full size, at mode 0600. Deleting it after you pay is up to you

• OTP required: You always supply the OTP yourself

• Confirm before order: Preview shown, you confirm final purchase

• Session isolation: Each platform login is separate

• Payment QRs are never auto-opened unless you ask: set_preferences(open_qr: "true") opts in to launching an image viewer when a QR is generated. It is off by default because it starts a process on your machine

Why a payment QR opens in a separate viewer

MCP clients render tool-result images inside a short container with its own scrollbar — Claude Desktop's Place order block is one — so a QR sent inline is clipped across the fold and will not scan from the chat. The protocol has no way for a server to change that layout, so the full-resolution PNG is always written to ~/.quick-commerce-mcp/sessions/ and its path returned in the message. Set open_qr to "true" to have it also launch in your image viewer automatically.

🏗️ Architecture

Each platform is driven through a single shared browser page, so tool calls that touch the same platform are serialised automatically — you can fire several at once and they queue rather than collide. Calls against different platforms run in parallel, so comparing three platforms is still concurrent.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Claude    │────▶│  MCP Server  │────▶│  Playwright │
│  /Cursor    │◀────│  (this repo) │◀────│  Automation │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                                │
                              ┌─────────┴──────────┐
                              │ Zepto | Blinkit |  │
                              │ Swiggy Instamart   │
                              └────────────────────┘

📋 Status

See the versioned flow-status table for the single source of verification scope and known limitations. Implemented tools and older demonstrations are not a claim of current end-to-end support.

🤝 Contributing

This is a personal project. Open to suggestions!

Use Node.js 24, run npm ci, and install fixture browsers with npx playwright install chromium. Run npm run setup:hooks once per checkout. The pre-commit hook runs npm run check (the full test suite, lint, and browser helper syntax checks, and the high-severity dependency audit), refuses unstaged code changes, and checks that generated dist/ files are staged. GitHub Actions runs the same checks on pushes and pull requests using the committed dependency lockfile.

Tests cover cart persistence and rejected writes, OTP/session restoration, saved-address selection, MCP reconnect/handshake and preference persistence, payment preferences and category navigation, and native and linked wallet preparation/confirmation across all four platforms. They use local browser fixtures and never charge a real account. Live payment execution still requires separate verification; passing fixtures do not establish support for every current merchant checkout variant.

⚠️ Disclaimer

This is an unofficial project, not affiliated with Zepto, Blinkit or Swiggy. It automates a real browser logged in as you. Automating these sites may violate their Terms of Service and can get your account rate-limited or blocked; you use it at your own risk.

place_order spends real money. It only runs after a two-step confirmation, but always check the order summary your assistant shows you before approving. Sessions (login cookies) are stored unencrypted in ~/.quick-commerce-mcp/sessions/; keep that folder private.

Created: 2026-02-12

BigBasket UPI QR handoff

The observed BigBasket Juspay desktop UPI screen offers Generate QR Code. It has no UPI-ID/phone input, and the bank handles shown underneath are suggestions, not a saved UPI account. prepare_payment opens this screen without generating a transaction. place_order(payment_method: "upi_qr") prepares a confirmation token; the confirmed second call generates once and returns the QR image and private file for scanning with any UPI app. It reports pending, never a paid/confirmed order. A shared wallet/UPI attempt journal prevents duplicate generation or fallback after an uncertain result, including across MCP restarts. Reconcile the attempt in the merchant app before clearing that guard. Cart, address and payable amount must still match the approved preview. Live QR generation was verified on 2026-10-04: Juspay returned a GIF QR, normalized from native image pixels to PNG and successfully decoded as a UPI payment for ₹162.59 INR to INNOVATIVE RETAIL CONCEPTS PRIVATE LIMITED. The adapter now checks decodability, exact amount, currency and merchant before returning a QR as ready. The image and private full-resolution file are returned to the client; no payment was made. Fixtures include GIF extraction and mismatched/invalid payloads. Actual payment completion remains untested. UPI collect is not offered in the observed screen and is not enabled for BigBasket.

Post-payment tracking

Confirmed place_order calls now persist the payment attempt before dispatch, then inspect merchant order-detail redirects without leaving the payment screen. get_payment_status(platform, wait_ms: 30000) watches the current attempt across all four platforms, including new tabs. It distinguishes confirmed orders, failed payments, cancellation, pending and unknown outcomes. An order-history URL alone never proves success, and a confirmed order is marked paid only if the merchant explicitly shows payment completion. Baseline old orders, unrelated merchant hosts, history lists, conflicting status text and mismatched amounts cannot count as completion. Tracking survives MCP restarts. A matching terminal outcome archives and releases the wallet/UPI attempt guard without retrying a payment. No navigation, payment submission or automatic fallback happens during watching. Redirect tracking is fixture-tested on all four apps; the BigBasket unpaid QR redirect and merchant cancellation were observed live. Paid completion still requires the final user-controlled payment test.

BigBasket blocked-browser recovery (issue #1)

BigBasket may refuse the default headless browser even with a correct OTP. Logging in to your normal browser or an incognito window does not log MCP in: it uses a separate profile. Do not keep requesting OTPs on a blocked page.

Install the browser once with npx playwright install chromium. Fully quit Claude Desktop or stop the MCP server first, so its headless browser releases the dedicated profile. Then keep a separate terminal running:

npx -y --package=quick-commerce-mcp quick-commerce-mcp-bigbasket-browser

Reopen Claude Desktop (or reconnect your MCP client) after the helper reports ready. MCP automatically attaches to that dedicated browser. Ask the assistant to check BigBasket login, then supply your phone number, pincode and a fresh OTP only if requested. Keep the terminal running throughout shopping.

On native Windows this command defaults to an invisible isolated desktop. On macOS/Linux it opens a visible browser; true headless access is not assured. If a challenge requires manual interaction, stop the helper and rerun it with --visible. Complete the check in that dedicated browser, then reconnect MCP. Use the same OS account and environment for the helper and MCP; a Windows helper does not publish its endpoint into a WSL home directory. WSL deployments must use the Windows bridge described in the README. QC_CHROME_PATH can select an installed Chrome executable instead of Playwright Chromium. The background helper does not require Codex or a Codex-managed Node installation.

This recovery command is available starting with 1.6.1, or from the current source checkout (node scripts/open-bigbasket-browser.mjs). Do not assume an older cached npx package includes it. Fresh Windows background startup, MCP-compatible browser attachment and the logged-out BigBasket login button were verified with a temporary profile on 2026-10-05. The isolated desktop now starts on a blank page before MCP navigates, avoiding the fresh-profile attachment timeout observed when it launched directly into BigBasket. A clean native Windows installation of the candidate tarball was also tested with freshly downloaded Chromium, without QC_CHROME_PATH or a custom CDP URL. MCP sent one OTP, completed login, and returned the saved Bangalore address. A fresh MCP process preserved the pending OTP screen; after verification, a complete browser restart plus another fresh MCP process remained logged in without requesting another OTP. One separate clean run timed out waiting for login controls, so initial site loading can still fail. These checks apply to the Windows recovery route, not true headless browsing or all operating systems. Actual payment submission remains untested in this recovery route.

Linux and macOS recovery verification (2026-10-05)

A clean candidate tarball installation was checked in Ubuntu 24.04 WSL x86-64 using Node 24 and freshly downloaded native Linux Chromium (Playwright 1.63.0). No Windows executable, Windows bridge, QC_CHROME_PATH, or custom CDP URL was used. The ordinary headless MCP route was blocked by BigBasket. The recovery helper on an Xvfb virtual display started successfully, published a private loopback endpoint, attached through a fresh stdio MCP connection, and reached the login phone form. Profile permissions were 0700; endpoint permissions were 0600. BigBasket then rejected the single OTP request with HTTP 400 and did not show an OTP screen. Linux login completion and persistence are therefore not verified. The status alone does not establish why the server rejected it.

On Linux, an Xvfb display keeps headed Chromium off the user desktop:

# Stop the existing MCP server first. On Ubuntu, install xvfb and xauth if absent.
xvfb-run -a npx -y --package=quick-commerce-mcp quick-commerce-mcp-bigbasket-browser

Keep the wrapper running while MCP attaches. This is headed Chromium on a virtual display; access and login still depend on BigBasket's site checks. The recovery executable requires 1.6.1 or later, or a source checkout; 1.6.0 does not expose that executable.

macOS uses the native Playwright Chromium executable and a dedicated visible browser, without the Windows PowerShell desktop helper. Playwright currently supports macOS 14 or later; use a supported Node release such as Node 24 (system requirements). The validation workflow now runs the build and browser regressions on both Ubuntu and a native macOS runner. Fixture tests do not establish live BigBasket login acceptance. A fresh Mac login still needs on-device verification.