Mercadona Server

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
get_shopping_guide	The shopping playbook. Read first.
auth_status	Whether the session is valid and how long the token lasts.
login	Open a browser to sign in (handles 2FA); saves the session locally.
search_products	Find products + ids in your delivery area.
get_product	Details for a single product by id.
get_cart	The current real cart: items, quantities, total.
get_my_regulars	What you usually buy (precision = most bought, recall = also bought).
get_purchase_history	Past orders: date, total, status, item count.
get_order_items	Items in a past order, without adding anything.
get_delivery_slots	Available delivery windows for your address.
add_to_cart	Add a product by id (increments if present).
set_quantity	Set the exact quantity (0 removes).
remove_from_cart	Remove a product entirely.
reorder_order	"Buy again" — add a whole past order in one step.

Requirements

• Node.js ≥ 18
• Google Chrome installed (the login tool opens it via Playwright's chrome channel)

Build

npm install
npm run build      # bundles src/ -> dist/server.mjs with esbuild

playwright-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 .mcpb does 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.mjs

The folder then contains everything an unpacked extension needs:

manifest.json
icon.png
dist/server.mjs
node_modules/playwright-core

In 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.mjs

Point 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/mcpb

This 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.json

This 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 — in localStorage under MO-user. The login flow captures Playwright storageState, and store.mjs reads the token straight out of it. No separate token endpoint.
• API (src/mercadona/api.mjs): a thin client over tienda.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-lock version, 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