Skip to content
Back to search

open-supermarkets

"Open-source supermarket infrastructure across 13 provider integrations in 9 countries. Search live catalogues and prices, compare retailers, build baskets, inspect slots and orders, and preview checkout through CLI, HTTP, MCP or agent skills."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/abracadabra50--open-supermarkets/badge.svg)](/listings/abracadabra50--open-supermarkets)

HTML

<a href="/listings/abracadabra50--open-supermarkets"><img src="/api/listings/abracadabra50--open-supermarkets/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 179 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: open-supermarkets
  3. description: "Open-source supermarket infrastructure across 13 provider integrations in 9 countries. Search live catalogues and prices, compare retailers, build baskets, inspect slots and orders, and preview checkout through CLI, HTTP, MCP or agent skills."
  4. license: MIT
  5. compatibility: Node.js 18+, TypeScript. Playwright only for browser-auth providers. Delivery areas and capabilities vary by retailer.
  6. metadata:
  7. author: zish
  8. version: "3.0.0"
  9. repository: https://github.com/abracadabra50/open-supermarkets
  10. tags: [groceries, supermarket, grocery-api, price-comparison, tesco, sainsburys, ocado, tesco-hu, migros, albert-heijn, mercadona, ahorramas, kroger, instacart, uk, netherlands, belgium, spain, hungary, switzerland, usa, canada, shopping, automation, mcp, agent-tool]
  11. allowed-tools: Bash({baseDir}/node:*), Bash(supermarket:*), Bash(npm:run:supermarket:*)
  12. ---
  13. # Open Supermarkets
  14. One common grocery interface across supermarket providers in the UK, Europe and North America.
  15. Use it when an agent needs live grocery search, retailer comparison, basket operations, delivery slots, order history or a checkout preview.
  16. ## Current coverage
  17. Current `main` includes 13 provider integrations across 9 countries:
  18. | Provider | Market | Main capabilities |
  19. |---|---|---|
  20. | Sainsbury's | UK | search, basket, slots, checkout, orders |
  21. | Tesco | UK | search, basket, slots, checkout, orders |
  22. | Ocado | UK | search, basket, read slots, orders |
  23. | Lidl Ireland | Ireland | search |
  24. | Albert Heijn | Netherlands | search |
  25. | Albert Heijn België | Belgium | search |
  26. | Mercadona | Spain | search |
  27. | AhorraMás | Spain | search |
  28. | Tesco Magyarország | Hungary | search, basket |
  29. | Migros | Switzerland | search, guest basket |
  30. | Kroger | US | search |
  31. | Instacart | US, Canada | search, basket |
  32. | Instacart Web | US, Canada | search, basket |
  33. Run `supermarket providers` for the live registry-backed capability matrix.
  34. ## Quick start
  35. ```bash
  36. npx open-supermarkets providers
  37. npx open-supermarkets search "olive oil" --country ES --limit 5
  38. ```
  39. Or install globally:
  40. ```bash
  41. npm install -g open-supermarkets
  42. supermarket providers
  43. ```
  44. ## CLI
  45. ```bash
  46. # Search by country
  47. supermarket search "milk" --country NL --json
  48. supermarket search "leche" --country ES --json
  49. # Search a specific provider
  50. supermarket --provider tesco search "milk" --json
  51. supermarket --provider tesco-hu search "tej" --json
  52. # Basket and checkout where supported
  53. supermarket --provider tesco basket --json
  54. supermarket --provider tesco add PRODUCT_ID --qty 1
  55. supermarket --provider tesco checkout
  56. ```
  57. Checkout previews by default. Spending requires explicit confirmation.
  58. ## MCP
  59. Use the MCP server when the host supports Model Context Protocol:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "groceries": {
  64. "command": "npx",
  65. "args": ["-y", "open-supermarkets", "mcp"]
  66. }
  67. }
  68. }
  69. ```
  70. Prefer batch tools for multi-item workflows:
  71. - `grocery_search_batch`
  72. - `grocery_basket_add_batch`
  73. Use `grocery_providers` to inspect the providers exposed by the MCP server.
  74. ## How to reason about providers
  75. Providers are capability-based.
  76. Do not assume that because search works, basket or checkout also works. Check the provider capability matrix first.
  77. Search-only integrations are intentionally first-class because catalogue and pricing access is useful even when authenticated shopping is not available.
  78. ## Product selection
  79. The provider returns candidates. The agent should decide what to buy using user context such as:
  80. - requested ingredient/product;
  81. - pack size;
  82. - quantity;
  83. - budget;
  84. - dietary restrictions;
  85. - brand preference;
  86. - recipe;
  87. - household size.
  88. Do not blindly select the first or cheapest absolute-price result.
  89. ## Availability
  90. Treat availability as a truth claim.
  91. `in_stock` (`inStock` in batch output) is `true`, `false` or `null`. `null` means the retailer did not say. Do not read it as in-stock or out-of-stock. Tell the user it is unknown, or check before checkout.
  92. A `null` price (shown as "price unknown") is not zero. Never treat it as the cheapest option, and do not quote a basket total that includes it.
  93. | `in_stock` / batch `inStock` | Meaning |
  94. |---|---|
  95. | `true` | In stock |
  96. | `false` | Explicitly out of stock |
  97. | `null` | Retailer did not provide a reliable stock signal |
  98. Use strict equality (`=== true`, `=== false`, `=== null`) when branching on stock. `!product.in_stock` conflates unavailable and unknown; `product.in_stock === false` identifies only explicit out-of-stock signals. When stock is `null`, report it as unknown and ask the user to check with the retailer.
  99. ## Authentication
  100. Authentication varies by provider:
  101. - none;
  102. - anonymous/guest session;
  103. - API key;
  104. - OAuth;
  105. - credentials;
  106. - browser-imported session.
  107. Follow the provider manifest and provider-specific notes rather than assuming every retailer supports scripted login.
  108. ## Error handling
  109. A legitimate empty search may return an empty product list.
  110. Authentication failures, rate limits, malformed retailer responses and bot/WAF challenges should remain errors. Do not treat them as "no products found".
  111. ## Provider-specific skills
  112. Dedicated notes currently exist for:
  113. - [Sainsbury's](skills/sainsburys.md)
  114. - [Tesco](skills/tesco.md)
  115. - [Ocado](skills/ocado.md)
  116. - [Tesco Magyarország](skills/tesco-hu.md)
  117. - [Migros](skills/migros.md)
  118. Providers without a dedicated skill file still work through the common provider interface where their declared capabilities are supported.
  119. ## Nutrition and allergens
  120. `--enrich` adds Open Food Facts data such as Nutri-Score, NOVA group, ingredients and allergens.
  121. Treat enrichment as auxiliary metadata. Exact identity matching is preferred; fuzzy matches should never be presented as definitive allergy information.
  122. ## References
  123. - [README.md](README.md)
  124. - [AGENTS.md](AGENTS.md)
  125. - [docs/API.md](docs/API.md)
  126. - [docs/PROVIDER-SPEC.md](docs/PROVIDER-SPEC.md)
  127. - [CONTRIBUTING.md](CONTRIBUTING.md)
README.md · README · 345 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # open&#8203;-supermarkets
  3. ### One open interface to the world's supermarkets
  4. **Search live catalogues and prices, compare retailers, build baskets and automate grocery shopping<br>across 13 provider integrations in 9 countries, through CLI, HTTP and MCP.**
  5. **CLI · HTTP API · MCP · Agent Skills**
  6. <br>
  7. [![npm](https://img.shields.io/npm/v/open-supermarkets?color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/open-supermarkets)
  8. [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
  9. [![Countries](https://img.shields.io/badge/countries-9-2ea44f)](#what-works-where)
  10. [![Providers](https://img.shields.io/badge/providers-13-2ea44f)](#what-works-where)
  11. [![No credentials](https://img.shields.io/badge/5%20countries-no%20credentials-orange)](#what-works-where)
  12. [![CI](https://github.com/abracadabra50/open-supermarkets/actions/workflows/ci.yml/badge.svg)](https://github.com/abracadabra50/open-supermarkets/actions/workflows/ci.yml)
  13. [![MCP](https://img.shields.io/badge/MCP-22%20tools-6E56CF)](#connect-an-agent)
  14. [![Stars](https://img.shields.io/github/stars/abracadabra50/open-supermarkets?style=flat&color=yellow)](https://github.com/abracadabra50/open-supermarkets/stargazers)
  15. 🇬🇧 &nbsp;🇮🇪 &nbsp;🇳🇱 &nbsp;🇧🇪 &nbsp;🇪🇸 &nbsp;🇭🇺 &nbsp;🇨🇭 &nbsp;🇺🇸 &nbsp;🇨🇦 &nbsp;&nbsp;·&nbsp;&nbsp; [**your country next?**](#bring-your-supermarket)
  16. </div>
  17. ---
  18. > **The demo to build:** “Plan five high-protein family dinners under £60. No pork, no nuts. Compare Tesco, Sainsbury's and Ocado, choose sensible pack sizes, build the basket and show me before checkout.”
  19. >
  20. > A short end-to-end demo belongs here. If you build one with Open Supermarkets, open a PR and we'll feature it.
  21. ```console
  22. $ supermarket compare milk
  23. Ocado Ocado British Semi Skimmed Milk 2 Pints £1.20 ← best
  24. Sainsbury's Sainsbury's British Semi Skimmed 2.27L £1.75
  25. Tesco Tesco British Semi Skimmed Milk 2.272L £1.75
  26. $ supermarket search leche --country ES
  27. Leche semidesnatada Hacendado €5.04 / 6l
  28. $ supermarket search melk --country NL
  29. Campina Halfvolle melk €1.89 / 1,5 l
  30. ```
  31. **Open Supermarkets now spans the UK, Ireland, the Netherlands, Belgium, Spain, Hungary, the US and Canada.**
  32. Several catalogue providers need no account or retailer credentials at all, while authenticated
  33. providers progressively expose baskets, slots, orders and checkout.
  34. ---
  35. ## Try it
  36. ```bash
  37. npx open-supermarkets providers
  38. npx open-supermarkets search "olive oil" --country ES --limit 5
  39. ```
  40. Or install it globally:
  41. ```bash
  42. npm install -g open-supermarkets
  43. supermarket providers
  44. ```
  45. The canonical command is `supermarket`; `open-supermarkets` is an npm-friendly alias.
  46. The old `groc` alias remains temporarily for backwards compatibility and will disappear
  47. in v4.
  48. From source:
  49. ```bash
  50. git clone https://github.com/abracadabra50/open-supermarkets.git
  51. cd open-supermarkets && npm install && npm link
  52. npx playwright install chromium # only for browser-auth providers
  53. ```
  54. ---
  55. ## What Open Supermarkets is
  56. Open Supermarkets is a common, open-source interface over supermarket storefronts and APIs.
  57. It normalises the retailer-specific plumbing so applications and agents can work against one
  58. provider model instead of rebuilding Tesco, Sainsbury's, Ocado, Albert Heijn, Mercadona,
  59. AhorraMás, Kroger, Instacart and regional integrations independently.
  60. A shopping agent should still decide *what* makes sense for the person. Open Supermarkets
  61. handles the retail plumbing underneath it:
  62. - search real supermarket catalogues and current prices;
  63. - compare retailers without forcing every agent to build retailer integrations;
  64. - build and mutate live baskets where the provider supports it;
  65. - inspect delivery slots and order history;
  66. - enrich products with nutrition and allergen data;
  67. - preview checkout safely before any money is spent.
  68. Supermarkets rarely expose public shopper APIs. Without a shared layer, every meal
  69. planner, price tracker and shopping agent reimplements the same brittle integration
  70. for one retailer and eventually abandons it. This is that layer, done once, in the open.
  71. ---
  72. ## Connect an agent
  73. ### MCP
  74. For Claude Desktop, Cursor or anything speaking Model Context Protocol:
  75. ```json
  76. {
  77. "mcpServers": {
  78. "groceries": {
  79. "command": "npx",
  80. "args": ["-y", "open-supermarkets", "mcp"]
  81. }
  82. }
  83. }
  84. ```
  85. If you install the package globally, use `supermarket-mcp` directly.
  86. A useful first prompt:
  87. > *Plan a week of high-protein dinners, no pork and no nuts. Price the shop at Tesco, show me the basket and do not place an order.*
  88. The server exposes 22 tools, including batch primitives designed to stop agents burning
  89. one tool call per ingredient:
  90. | MCP tool | Purpose |
  91. |---|---|
  92. | `grocery_search` · `grocery_compare` | Find and compare products |
  93. | **`grocery_search_batch`** · **`grocery_basket_add_batch`** | **Many at once — prefer these** |
  94. | `grocery_basket_*` | View, add, remove, update, clear |
  95. | `grocery_slots` · `grocery_book_slot` | Delivery slots |
  96. | `grocery_checkout` | Preview/place an order; `dry_run` defaults to **true** |
  97. | `grocery_favourites` · `ocado_regulars` · `tesco_staples` | Repeat-purchase lists |
  98. | `grocery_orders` | Order history |
  99. ### Agent skills
  100. [`SKILL.md`](SKILL.md) is the top-level skill. [`skills/`](skills/) contains provider
  101. skills for the quirks that actually matter: Tesco cookie import, Ocado category paths,
  102. Sainsbury's favourites and more. Drop them into Claude Code, OpenClaw or another harness
  103. that reads `SKILL.md`.
  104. ### HTTP
  105. `supermarket-api` exposes the same core capabilities over plain HTTP for agents that
  106. have network access but cannot execute local commands.
  107. ### CLI
  108. Everything ultimately rests on a scriptable CLI contract:
  109. ```bash
  110. supermarket search "olive oil" --country ES --limit 5 --json
  111. ```
  112. ---
  113. ## What works where
  114. Providers declare what they can actually do. Search needs no account almost everywhere;
  115. checkout needs an account, address and payment method, so it exists for fewer.
  116. | Provider | Country | Search | Basket | Slots | Checkout | Auth |
  117. |---|---|:-:|:-:|:-:|:-:|---|
  118. | Tesco | 🇬🇧 | ✓ | ✓ | ✓ | ✓ | browser session |
  119. | Sainsbury's | 🇬🇧 | ✓ | ✓ | ✓ | ✓ | email + password |
  120. | Ocado | 🇬🇧 | ✓ | ✓ | read-only | — | email + password |
  121. | Lidl Ireland | 🇮🇪 | ✓ | — | — | — | **none** |
  122. | Albert Heijn | 🇳🇱 | ✓ | — | — | — | **none** |
  123. | Albert Heijn België | 🇧🇪 | ✓ | — | — | — | **none** |
  124. | Mercadona | 🇪🇸 | ✓ | — | — | — | **none** |
  125. | AhorraMás | 🇪🇸 | ✓ | — | — | — | **none** |
  126. | Kroger *+ Ralphs, Fred Meyer, King Soopers, Harris Teeter, QFC* | 🇺🇸 | ✓ | — | — | — | free API key |
  127. | Instacart | 🇺🇸 🇨🇦 | ✓ | ✓ | — | via link | partner key |
  128. | Instacart *(unofficial)* | 🇺🇸 🇨🇦 | ✓ | ✓ | — | — | browser session |
  129. | Tesco Magyarország | 🇭🇺 | ✓ | ✓ | — | — | browser session (basket only) |
  130. | Migros | 🇨🇭 | ✓ | ✓ | — | — | **none** (guest basket) |
  131. `supermarket providers` prints this live from the registry. The manifest is the source
  132. of truth rather than a hand-maintained marketing claim.
  133. Lidl Ireland is search-only. Lidl Plus loyalty prices and conditional multibuy prices are
  134. not substituted for the regular shelf price. Product availability uses three states:
  135. `in_stock: true` means available, `false` means explicitly unavailable, and `null` means
  136. the retailer provided no reliable stock signal. Batch search exposes the same states as `inStock`.
  137. Ocado slot booking and checkout are blocked by AWS WAF. Reading slots works; committing
  138. to one does not. The manifest therefore does not claim those capabilities.
  139. ---
  140. ## Built for how agents actually work
  141. A week of meals can mean thirty ingredients. One at a time, that becomes thirty searches
  142. plus thirty basket writes: sixty process starts, sixty MCP round trips and sixty tool
  143. results filling the model's context.
  144. ```console
  145. $ echo '["semi skimmed milk","free range eggs","chicken breast","broccoli"]' \
  146. | supermarket search --batch - --provider ocado --limit 2
  147. ```
  148. ```json
  149. {
  150. "provider": "ocado",
  151. "results": [
  152. {
  153. "query": "semi skimmed milk",
  154. "products": [
  155. {
  156. "id": "73f814b7",
  157. "name": "Ocado British Semi Skimmed Milk 2 Pints",
  158. "price": 1.20,
  159. "currency": "GBP",
  160. "size": "1.136L",
  161. "unit": "1.06/1.136L",
  162. "inStock": true
  163. }
  164. ]
  165. }
  166. ]
  167. }
  168. ```
  169. Then let the model choose using the context it already has and add its picks together:
  170. ```bash
  171. supermarket add --batch picks.json
  172. ```
  173. Batch search returns candidates. **It deliberately does not decide what to buy.** The
  174. model knows the meal plan, budget, dietary constraints and whether leftovers are useful;
  175. the supermarket integration does not.
  176. Provider code is also lazy-loaded. Shopping in the UK does not load Spanish provider
  177. code or pay Playwright startup cost for a retailer you never use.
  178. ---
  179. ## Nutrition and allergens
  180. `--enrich` adds Nutri-Score, NOVA processing group, allergens and ingredients using
  181. [Open Food Facts](https://openfoodfacts.org) across every provider and country.
  182. ```console
  183. $ supermarket search nutella --provider kroger --enrich
  184. Nutella® Hazelnut Spread with Cocoa $6.49 / 13 oz
  185. Nutri-Score E · NOVA 4 · allergens: milk, nuts, soybeans · matched by barcode
  186. ```
  187. Matching is intentionally conservative. Where a provider exposes a barcode, the lookup
  188. can be exact. Where it does not, name matching must clear strict guards. A miss shows
  189. nothing; a false positive can show the wrong allergen, which is much worse.
  190. Never rely on it as medical or allergy advice. Check the product packaging.
  191. ---
  192. ## Bring your supermarket
  193. This project compounds in value as coverage grows. A contributor can add the supermarket
  194. they can actually test without implementing the entire shopping lifecycle: search-only
  195. providers are first-class, while basket, slots, checkout and orders are separate capabilities.
  196. **AhorraMás — Spain — search.** Search requires no credentials and reads the
  197. anonymous Salesforce Commerce Cloud storefront. Availability can depend on the
  198. selected location; basket operations are not supported yet.
  199. Before starting, read [`docs/providers/evaluated.md`](docs/providers/evaluated.md). It
  200. records providers already investigated, what worked, what failed and when. That avoids
  201. every contributor rediscovering the same bot wall or dead endpoint.
  202. The minimum provider shape is intentionally small:
  203. ```ts
  204. export class MySupermarketProvider {
  205. readonly name = 'mysupermarket';
  206. async search(query: string, opts?: SearchOptions): Promise<Product[]> { /* ... */ }
  207. }
  208. ```
  209. Register it in `src/providers/registry.ts`, add tests that run without credentials, and
  210. open a PR. [`src/providers/ah.ts`](src/providers/ah.ts) is a useful reference for a small
  211. anonymous-search provider. [`src/providers/tesco-hu/`](src/providers/tesco-hu/) shows a
  212. search-plus-session provider that talks GraphQL and imports browser cookies.
  213. Read [`CONTRIBUTING.md`](CONTRIBUTING.md) for the contribution contract.
  214. ### The rules that stop this rotting
  215. - Every provider has a maintainer of record.
  216. - `core` integrations are maintained here and CI-tested; `community` integrations are best-effort and labelled as such.
  217. - Declare only capabilities that have actually been implemented and verified.
  218. - Credit protocol research you learned from rather than quietly absorbing it.
  219. - Never put retailer credentials, session cookies or payment data in issues, tests or commits.
  220. ---
  221. ## Honest caveats
  222. **Most integrations are unofficial.** Retailers change APIs without notice and some
  223. deploy bot protection. A red provider can mean the retailer changed, not your setup.
  224. **Automated access may conflict with retailer terms.** This project is intended for
  225. personal automation of your own shopping. Understand the terms that apply to you.
  226. **Checkout previews by default.** `supermarket checkout` shows the order and places
  227. nothing. Spending money requires `--confirm`; the MCP checkout tool defaults to
  228. `dry_run: true`.
  229. **Upcoming orders are not trolleys.** While a Tesco order is open for amending, the
  230. account's basket *is* that order, so an add changes the next delivery. Basket writes
  231. refuse in that state and name the order; pass `--amend` (MCP `amend: true`, HTTP
  232. `amend=1`) to edit it on purpose. `supermarket basket --json` reports it under `amend`.
  233. **Sessions expire.** Cookie-auth providers need re-importing periodically. Authentication
  234. failures are surfaced explicitly rather than masquerading as empty search results.
  235. For security-sensitive reports, read [`SECURITY.md`](SECURITY.md).
  236. ---
  237. ## Built with Open Supermarkets
  238. Using this in an agent, meal planner, price tracker, Alexa workflow or something stranger?
  239. Open a PR adding it here. Real implementations are far more useful than another invented
  240. example.
  241. ---
  242. ## Credits
  243. Protocol knowledge, reimplemented rather than copied, from:
  244. - [gwillem/appie-go](https://github.com/gwillem/appie-go) — Albert Heijn (Go, MIT)
  245. - [kleinjm/instacart_api](https://github.com/kleinjm/instacart_api) — Instacart web (Ruby, MIT)
  246. - [CupOfOwls/kroger-api](https://github.com/CupOfOwls/kroger-api) — Kroger (Python, MIT)
  247. - [Open Food Facts](https://openfoodfacts.org) — global product data (ODbL)
  248. Open Food Facts is a nonprofit. If this project is useful to you, consider supporting
  249. the volunteers maintaining that dataset.
  250. MIT. Not affiliated with, endorsed by or connected to any retailer named here.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.