Skip to main content
Glama
Mercadona MCP Server

Mercadona MCP Server

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

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.

Related MCP server: Ametller Origen

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.

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

Available Tools

14 tools
add_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

    A3.9/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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