Mercadona MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mercadona MCP Server search for whole wheat bread"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Mercadona for Claude
Shop your Mercadona online groceries by talking to Claude.
This is an MCP server that drives your own authenticated Mercadona session. Claude can search the catalog scoped to your delivery area, read your purchase history and "my regulars," and add, change, or remove items in your real cart — so you and Claude fill it together. Products are presented as a photo grid.
You stay in control of payment. There is no checkout or payment tool, by design. Claude fills the cart; you review and pay in the Mercadona app, where Strong Customer Authentication happens.
It installs as a Claude Desktop extension (described by manifest.json) — load it unpacked
via developer mode (see Install; the packed .mcpb doesn't install reliably). It can
also run as a plain local MCP server.
Independent project. Not affiliated with, endorsed by, or sponsored by Mercadona. macOS-focused.
Tools
Tool | What it does |
| The shopping playbook. Read first. |
| Whether the session is valid and how long the token lasts. |
| Open a browser to sign in (handles 2FA); saves the session locally. |
| Find products + ids in your delivery area. |
| Details for a single product by id. |
| The current real cart: items, quantities, total. |
| What you usually buy ( |
| Past orders: date, total, status, item count. |
| Items in a past order, without adding anything. |
| Available delivery windows for your address. |
| Add a product by id (increments if present). |
| Set the exact quantity ( |
| Remove a product entirely. |
| "Buy again" — add a whole past order in one step. |
Related MCP server: Ametller Origen
Requirements
Node.js ≥ 18
Google Chrome installed (the
logintool opens it via Playwright'schromechannel)
Build
npm install
npm run build # bundles src/ -> dist/server.mjs with esbuildplaywright-core is kept external (it stays in node_modules); everything else is bundled into
dist/server.mjs.
Install
Install it unpacked (developer mode). This is the recommended and reliable path — the packed
.mcpbdoes not currently install cleanly in Claude Desktop, so use the unpacked folder below.
As an unpacked Claude Desktop extension (recommended)
Load this folder directly. The build output (dist/) and runtime dependency
(node_modules/playwright-core) are git-ignored, so after cloning you must produce them first:
npm install # installs playwright-core into node_modules/
npm run build # writes dist/server.mjsThe folder then contains everything an unpacked extension needs:
manifest.json
icon.png
dist/server.mjs
node_modules/playwright-coreIn Claude Desktop: Settings → Extensions → Advanced settings → "Install unpacked extension…",
then select this folder (the one containing manifest.json). It loads as the "Mercadona" extension;
run the login tool once to sign in.
Requirements: Node ≥ 18 on your PATH and Google Chrome installed (the login tool opens
it). Rebuild (npm run build) after changing anything under src/, then reload the extension.
As a local MCP server
If you don't want a Claude Desktop extension at all, run it as a plain MCP server:
npm install && npm run build
node dist/server.mjsPoint any MCP client at node /path/to/dist/server.mjs. For Claude Desktop's config:
{
"mcpServers": {
"mercadona": {
"command": "node",
"args": ["/absolute/path/to/mercadona-claude-extension/dist/server.mjs"],
"env": { "MERCADONA_BROWSER_CHANNEL": "chrome" }
}
}
}As a packed Claude Desktop extension (.mcpb)
⚠️ Not currently recommended — Claude Desktop does not install the packed bundle reliably. Use the unpacked path above instead. Kept here for completeness.
npm run pack # builds dist/, then packs a .mcpb via @anthropic-ai/mcpbThis produces a single .mcpb bundle (it includes dist/ and the production node_modules, i.e.
playwright-core).
Signing in
Run the login tool (or just ask Claude to log in). A Chrome window opens at the Mercadona store;
sign in and complete any 2FA. The extension waits until it sees your first authenticated request,
then saves the session to:
~/.mercadona/storage_state.jsonThis file holds your Mercadona auth and never leaves your machine. It is git-ignored here — do
not commit it. Tokens last a few days; re-run login when auth_status says it has expired.
Override the location with MERCADONA_STATE_PATH, or the browser with MERCADONA_BROWSER_CHANNEL
(default chrome).
How it works
Auth (
src/auth): Mercadona stores the logged-in user — including the API access token — inlocalStorageunderMO-user. Theloginflow captures PlaywrightstorageState, andstore.mjsreads the token straight out of it. No separate token endpoint.API (
src/mercadona/api.mjs): a thin client overtienda.mercadona.es/api. Catalog search goes through Mercadona's public, search-only Algolia index (scoped to your warehouse). Cart writes are a read-modify-write against the cart's optimistic-lockversion, retried once on conflict.Server (
src/server.mjs): registers the tools over stdio and turns expired-token / not-signed-in errors into friendly messages.
License
MIT © Igor Safonov
Available Tools
14 toolsadd_to_cartAdd to cartA
Add a product to the real cart by id (get the id from search_products or get_my_regulars first). If already present, increases the quantity. Returns the updated cart with its total.
Inputs: product_id (required), quantity.
auth_statusAuth statusA
Check whether the Mercadona session is valid and how long the token lasts.
Inputs: no named parameters.
get_cartGet cartB
Show the current real shopping cart (items, quantities, total).
Inputs: no named parameters.
get_delivery_slotsDelivery slotsA
Available delivery slots. Uses your first address if address_id is omitted.
Inputs: address_id.
get_my_regularsMy regularsA
Products you usually buy. kind='precision' = most bought; kind='recall' = also bought.
Inputs: kind.
get_order_itemsOrder itemsA
List the products in a past order (without adding anything). Defaults to the most recent order if order_id is omitted.
Inputs: order_id.
get_productGet productA
Get details for a single product by id.
Inputs: product_id (required).
get_purchase_historyPurchase historyB
List past orders (date, total, status, item count). Page is 1-based.
Inputs: page.
get_shopping_guideShopping guide (read first)A
Return the Mercadona shopping playbook: how to present products (ALWAYS as a photo-grid artifact), fill and review the real cart, use 'my regulars', and reorder past shops. Call this once at the start of any Mercadona task — before searching or adding to the cart — and follow it.
Inputs: no named parameters.
loginLog in to MercadonaA
Open a browser window to sign in to Mercadona. The user logs in (and handles any 2FA/SCA); the session is then saved so all other tools work. Call this when not signed in, or when a tool reports the session expired.
Inputs: no named parameters.
remove_from_cartRemove from cartB
Remove a product from the cart entirely. Returns the updated cart.
Inputs: product_id (required).
reorder_orderBuy again (reorder)A
Add all items from a past order to the cart in one step (a 'buy again'). Defaults to the most recent order. Skips items no longer available and reports them. Returns the updated cart.
Inputs: order_id.
search_productsSearch productsA
Find a product and its id (needed before add_to_cart), scoped to the user's delivery area. Use a short term; prefer the house brand 'Hacendado' unless asked otherwise. Returns matches with ids and prices.
Inputs: query (required), limit.
set_quantitySet quantityA
Set the exact quantity of a product in the cart. Quantity 0 removes it. Returns the updated cart.
Inputs: quantity (required), product_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool has a clearly distinct purpose: search vs product details, cart operations (add, remove, set quantity) are separate, past orders vs current cart, authentication, delivery slots, regulars, and a guide. No two tools overlap in function.
All tool names follow a consistent verb_noun pattern in snake_case, e.g., add_to_cart, get_cart, search_products, set_quantity. Minor deviations like 'auth_status' or 'login' are still clear and consistent with the style.
14 tools cover the essential operations for a grocery delivery service: authentication, search, product details, cart management, order history, and delivery slots. The number is well-scoped and neither too few nor excessive.
The tool set covers search, cart management, and history, but notably lacks a checkout or place_order tool. Users can fill a cart but cannot complete a purchase through the server. Delivery slots are viewable but not selectable. This is a significant gap for an e-commerce server.
Maintenance
Related MCP Connectors
Turn any shopping list into a ready-to-checkout grocery cart across 26 European supermarkets.
Run your online shop from Claude: orders, prices, sales, catalogue and design, confirmed by you.
Search live store shelves, verify delivery windows, and run instant AI agent checkouts.
AI shopping gateway for product search, inventory, carts, and merchant-hosted checkout.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables personalized Mercadona grocery orders via natural language, with Nutri-Score prioritization and supervised cart execution (no payment). Supports user intake, product search, and integration with external menu systems.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables shopping Ametller Origen online groceries through Claude, allowing catalog browsing, cart management, and order history access, with payment handled directly on the retailer's site.MIT
- AlicenseAqualityBmaintenanceEnables searching Mercadona Online products and reading or carefully updating a user's cart via the Model Context Protocol from the command line or ChatGPT Web.6MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude to search products, manage shopping carts, and compare prices across Continente, Pingo Doce, and Auchan, with optional skills for weekly meal planning and finding the cheapest basket.MIT