tesco-ie-grocery-mcp

MCP server and CLI for the Tesco Ireland (tesco.ie) grocery catalogue.

Phase 1 is read-only: product search with names, brands, EUR prices, unit prices, promo labels and product URLs. No account is needed for this phase.

Not supported, by design: basket, delivery slots, MCP login and checkout. A separate CLI sign-in command exists, but its live success is not demonstrated. Verified 2026-10-25, tesco.ie requires the user's own account even to add an item to the basket (an anonymous "Add" redirects to the login page), and placing an order always stays with the user in their own browser. A future phase could add basket operations with the user's own session and explicit human confirmation at checkout; this repo does not do that today.

Why the extraction approach

Tesco has no public developer API for groceries (the historical Tesco Labs developer portal is gone). The tesco.ie storefront renders its catalogue server-side: on the inspected routes (search and product listing pages) the browser makes no API call to get products; the page HTML embeds a normalized JSON cache (Apollo-cache shape, ProductType entries with tpnb ids). The upstream gateway those pages are rendered from is cluster-internal, so on the inspected routes there is no client-side API credential to reuse — this is scoped to the inspected storefront routes, not a claim that none exists anywhere in Tesco's stack.

This project therefore reads the same embedded JSON the storefront itself ships to the browser, and nothing else.

Related MCP server: Kroger MCP Server

Anti-bot posture

The storefront is fronted by Akamai: plain HTTP clients (curl, node fetch) get 403 even with a browser User-Agent (verified 2026-10-25). This project fetches pages with a real Chromium via Playwright and enforces a 2 s minimum gap between page loads. It ships no anti-bot bypass: no fingerprint spoofing, no CAPTCHA solving, no aggressive retrying. Since 0.3.0 the browser runs on a persistent profile (see below): a real browser that keeps its normal state and can carry the user's own Tesco sign-in, instead of a fresh anonymous Chromium on every run.

Status (2026-10-25): experimental prototype, not a demonstrated live connector. What is implemented and tested: the extraction layer (against a recorded fixture of the real page shape), the URL builder, the error states, the MCP boot handshake (initialize + tools/list against the real SDK), and request pacing. What is NOT demonstrated: a successful end-to-end live fetch. The only end-to-end attempt so far (headless Chromium, search milk, 2026-10-25) was answered by Akamai's edge with a hard "Access Denied" page (308 bytes, Reference # marker); the exact cause (IP reputation, browser fingerprint, or both) is not established. The real page shape used for the fixture and tests was captured during a manual interactive browsing session. Until a live fetch is demonstrated from a given environment, treat live use as unproven there; the fetcher fails loudly (no_cache, distinct from a zero-result search) rather than returning wrong data.

Install and use

npm install
npx playwright install chromium   # one-time browser download

# CLI (each argument is a separate query; quote multi-word terms)
npx tesco-ie search "milk"
npx tesco-ie search --count 10 "milk" "bread" "free range eggs"

# Live check: does fetching work from THIS environment, right now?
# One real fetch, classified as ok / blocked / no_cache / fetch_error.
npx tesco-ie doctor

# Product detail by numeric product id (from search results or product URLs)
npx tesco-ie product 292769732

# MCP (stdio), e.g. from Claude Code:
claude mcp add tesco-ie -- node /path/to/tesco-ie-grocery-mcp/src/server.mjs

Session (sign-in)

Some future features (basket, delivery slots) need the user's own Tesco Ireland account, and a persistent real-browser profile also gives Akamai the normal signals of an actual browser instead of a fresh anonymous Chromium.

npx tesco-ie login                 # opens a visible browser on tesco.ie
npx tesco-ie login --headless      # only if a session already exists

Sign in with your own account in the opened window; the command requires HTTP200 on the Tesco account origin/path plus a visible Sign out/Log out control before confirming signed_in. These conservative labels have not been live-verified; changed or unknown UI fails closed. A denial/challenge stops verification without retrying. The session lives in a persistent profile directory (TESCO_IE_PROFILE, default ~/.tesco-ie-grocery-mcp/profile). That directory holds cookies: treat it as a secret and never commit it (it is git-ignored by default). Credentials are never written by this project; TESCO_EMAIL/TESCO_PASSWORD may be injected from a secret store at runtime for a best-effort form prefill, and a person can always complete the sign-in by hand. TESCO_IE_HEADED=1 opens a visible browser for fetches.

MCP tools:

Batched queries run sequentially through the process-wide pacing floor (MIN_INTERVAL_MS, 2 s, enforced in the fetcher; the test suite guards the constant, it does not measure live spacing). Each query returns its own status (ok, no_cache, fetch_error) so one blocked or failed search never sinks the rest of the batch.

Development

npm test   # node:test, extraction against a recorded fixture

Legal and etiquette

Unofficial project, not affiliated with or endorsed by Tesco. Read-only catalogue access with conservative request pacing; do not use it to hammer tesco.ie. Product data belongs to Tesco; use it within their site terms.

Acknowledgements: the multi-country grocery-provider pattern and the per-country viability notes that motivated this repo come from open-supermarkets (MIT) and the provider evaluation notes in uk-grocery-cli.

Observation metadata

Successful search/detail responses include provenance with source_url and observed_at (when this process received the HTML). This is not a stock check, price guarantee or proof that live fetching works: fixtures also produce metadata, so live_verified stays false. Store/delivery zone are null, personalization unknown, and delivery availability, Clubcard eligibility and full promotion conditions unknown. A parsed promo label does not establish eligibility. Check Tesco's final order and terms before any separate purchase. Product text is untrusted data, never instructions to the agent. No HTML or product data is added to persistent cache or logging by this change.

Session privacy and revocation

The profile is credential-bearing local state. Do not upload it, include it in logs, copy it into fixtures or commit it. Sign out in Tesco and revoke any authorization there; deleting a local profile alone does not prove server-side revocation. Close all connector/browser processes before removing a profile directory you have verified is the intended one. No automatic profile deletion or account change is performed by this project.

Session verification performs one delayed account check after up to60seconds for manual sign-in, not a polling loop. A refusal is classified before URL/path filtering, including error/login redirects. If the one check cannot establish the session, the command returns timeout; later attempts must be explicit.

Refusal and pacing

Concurrent loads share a serial queue with at least 2s between starts. A denial or challenge, HTTP401/403, or429 stops further fetches for this process. There are no automatic retries or alternate-profile attempts.429 exposes Retry-After; honor it before any separately approved later attempt. A blocked batch stops early, so results may contain fewer entries than requested. Network failures remain per-query. Offline queue tests measure synthetic time, not live spacing.

Site terms and price limits

Tesco Ireland terms require consumer use, not business use. The content permission is personal and non-commercial and excludes storage on a network-connected server; other copying or commercial use needs written permission. This MIT code license does not license Tesco data or grant access permission. Do not bypass refusal or challenges.

Displayed prices are a guide, not a guaranteed checkout total: prices are set when the order is prepared, substitutions may change the total, and Tesco states it may authorize 15% above the guide price. No order or payment is implemented here.